Skip to main content
Codemod MCP (Model Context Protocol) provides AI assistants with tools for code analysis, AST manipulation, and codemod creation. The MCP server enables AI tools like Claude, Cursor, and others to understand code structure, create codemods, and perform automated code transformations.

​
Quick setup

Run the bootstrap command from anywhere: 
npx codemod ai
This is the main setup path for the AI-native CLI experience. It installs Codemod Master Skill and Codemod MCP for your coding agent so it can use Codemod CLI with built-in best practices for building, running, testing, and publishing codemods.
If you prefer to configure MCP yourself:
  • Open your IDE MCP settings.
  • Add the following MCP server entry:
{
  "mcpServers": {
    "codemod": {
      "command": "npx",
      "args": ["codemod@latest", "mcp"]
    }
  }
}
For Cursor IDE:
  • Open Cursor Settings
  • Navigate to MCP & Integrations
  • Click New MCP Server under MCP Tools
Ready to build? Follow the Quickstart for a complete walkthrough of building, testing, and publishing a codemod using MCP.

​
Available tools

The Codemod MCP server provides these operational tools for AI assistants:
  • dump_ast - Dump AST nodes in an AI-friendly format for given source code and language
  • get_node_types - Get compressed tree-sitter node types for specific programming languages
  • run_jssg_tests - Run tests for JSSG codemods with test cases
  • validate_codemod_package - Validate whether a codemod package is still a starter scaffold or incomplete

​
Available resources

The Codemod MCP server provides these guidance resources for AI assistants:
  • jssg-instructions - Docs-backed JSSG guidance for creating and testing transformation scripts
  • jssg-gotchas - Highest-priority JSSG gotchas before implementing transforms
  • ast-grep-gotchas - Highest-priority ast-grep gotchas before implementing transforms
  • jssg-utils-instructions - Docs-backed import utility guidance for getImport, addImport, and removeImport
  • jssg-runtime-capabilities-instructions - Runtime and capability guidance for LLRT/Node APIs and multi-file JSSG work
  • codemod-cli-instructions - Docs-backed CLI, package, and workflow guidance
  • codemod-creation-workflow-instructions - Docs-backed codemod authoring workflow guidance with a small local supplement
  • codemod-troubleshooting-instructions - Troubleshooting guidance for common Codemod CLI failures
  • codemod-maintainer-monorepo-instructions - Maintainer guidance for codemod monorepos and version-hop workspaces
  • sharding-instructions - Docs-backed sharding guidance
For codemod authoring, start by reading codemod-creation-workflow-instructions, then read jssg-gotchas and ast-grep-gotchas before writing source-transform code. When registry discovery does not find an exact package, agents should scaffold with direct codemod init. In non-interactive flows, agents should pass only values supplied by the user or task and rely on the CLI defaults/auth-derived author handling for optional metadata.

​
Why use Codemod MCP?

Codemod MCP democratizes code transformation by integrating robust deterministic engines into AI-powered development workflows:
  • Individual Developers: Take care of repetitive refactors without manual effort
  • Accessibility: Makes tackling tech debt more approachable for developers of all skill levels
  • AI Integration: Seamlessly integrates deterministic code transformation engines into AI IDE workflows

​
Best practices

When working with AI assistants through Codemod MCP, follow these guidelines for better results:
1

Be specific about output format

Tell the AI exactly what type of codemod you want:
  • jssg: TypeScript-based transformation scripts (codemods) that operate on ASTs generated by ast-grep, allowing you to transform code in any supported language.
  • ast-grep YAML rule: general-purpose transformations
  • shell workflow: complex multi-step migrations
2

Provide clear requirements

Describe your transformation in plain language with concrete examples:
  • Show before/after code snippets
  • Specify edge cases to handle or avoid
  • Include any constraints or special conditions
3

Break down complex changes

Instead of one large transformation, create focused codemods for specific patterns:
  • One codemod per logical change
  • Simpler codemods are more maintainable
  • Easier to test and debug individual transformations

​
Anonymous platform feedback

Codemod AI and MCP can submit short anonymous platform feedback when the user has explicitly consented. Agents must ask before enabling or submitting feedback. After the user consents, submit categorized feedback with: 
npx codemod ai feedback --category <category> --message <message>
Use short, thematic feedback only. Recommended categories are:
  • jssg: JSSG feature requests, runtime gaps, or transform-authoring friction
  • workflow: workflow feature requests or workflow authoring friction
  • ai-docs: AI docs resources that should be added, clarified, or reorganized
  • mcp: MCP tool, resource, or server behavior feedback
  • cli: CLI command or setup feedback
  • registry: registry discovery or package metadata feedback
  • package-validation: package validation checks that should be added or refined
  • other: feedback that does not fit the categories above
Do not include source code, secrets, auth tokens, private repository paths, user identity, or long transcripts. The CLI records and reports the consent timestamp automatically.

​
Troubleshooting

If the MCP server fails to start:
  • Ensure you have Node.js 16.0.0 or higher installed
  • Try running npx codemod@latest mcp manually to test
If MCP tools aren’t showing up:
  • Restart your AI client after adding the MCP server
  • Check the MCP server logs for error messages
  • Verify the JSON configuration syntax is correct
  • Ensure your AI client supports Model Context Protocol
For slow performance:
  • More complex transformations may take longer to build
  • Consider using specific file patterns to limit analysis scope
  • Check system resources and network connectivity
  • Use faster models if available