mcp-codemod

Migrates MCP Python SDK v1 code to v2 (the 2026-07-28 spec revision).

The TypeScript and Go SDKs ship a codemod for this migration. Python does not. Python developers get a 2,879-line migration guide and a lot of manual find-and-replace. This tool fills that gap.

Installation

pipx install mcp-codemod

pipx is the recommended way to install a command-line tool. It keeps the tool in its own environment and puts the command on your PATH.

If you would rather install into an existing virtualenv, pip works too:

pip install mcp-codemod

Note that on Ubuntu 24.04, Debian 12, Fedora, and other distributions that mark the system Python as externally managed (PEP 668), a bare pip install outside a virtualenv will be refused. Use pipx there.

Usage

mcp-codemod path/to/your/server           # dry run, prints a diff
mcp-codemod path/to/your/server --write   # applies the changes

Dry run is the default. Review the diff before writing.

Why not find-and-replace

The v2 models still accept camelCase at construction time. Only attribute access changed:

tool = Tool(name="forecast", inputSchema={"type": "object"})   # valid in v2
print(tool.inputSchema)                                        # broken in v2

Running sed -i 's/inputSchema/input_schema/g' breaks the first line while fixing the second. This tool handles both correctly because it operates on the concrete syntax tree, where a keyword argument is a Name node and attribute access is an Attribute node. Visiting only Attribute nodes cannot reach the keyword argument.

 tool = Tool(name="forecast", inputSchema={"type": "object"})
-print(tool.inputSchema, tool.outputSchema)
+print(tool.input_schema, tool.output_schema)

The implementation uses LibCST rather than the standard library ast module. A round trip through ast discards formatting: it reflows the file, strips comments, and normalises quote style. LibCST preserves every byte it does not deliberately change, so the resulting diff contains only the migration.

Changes applied automatically

Changes reported for manual review

Some v2 changes depend on runtime types, or on intent that the source code does not express. Applying those automatically would risk introducing bugs, so they are reported and the source is left unmodified.

F001 deserves particular attention. In v1, model_dump() emitted camelCase because the model fields themselves were camelCase. In v2 the same call emits snake_case, which other MCP implementations will not recognise. The migration guide describes the consequence directly:

No error is raised; the output is silently in the wrong shape.

This is not corrected automatically because the receiver cannot be statically proven to be an MCP protocol type. Adding by_alias=True to an unrelated Pydantic model would corrupt that model's output instead.

F009 is worth reading too. Eleven transport parameters moved off the MCPServer constructor and onto run() in v2, so this still raises TypeError at startup even after the class is renamed:

mcp = MCPServer("demo", host="127.0.0.1", port=8788)   # crashes in v2

They are not moved automatically because the destination is a different call site, which may be elsewhere in the file, in another module, or absent when the server is mounted as an ASGI app.

If you use the lowlevel Server

That migration is not automated, and the reason is worth stating plainly. Three things change at once: registration moves to the constructor, the handler signature becomes (ctx, params), and the handler must return the full result type instead of an unwrapped value. The last two mean rewriting the body, which means understanding what the body does. There is also an ordering trap, since the constructor is normally written above the handlers, so inserting on_list_tools=handler there raises NameError at import.

What the tool does instead is name the exact replacement for every handler it finds:

F008 stdio_server.py:56: Lowlevel `@…list_tools()` decorator. In v2, pass
`on_list_tools=<handler>` to the Server(...) constructor instead. The handler
signature becomes `(ctx: ServerRequestContext, params: PaginatedRequestParams
| None) -> ListToolsResult`, and it must return a full ListToolsResult rather
than an unwrapped value.

That covers all twelve lowlevel handlers, each with its own params and return type. F010 additionally catches request_ctx and server.request_context, which were removed outright.

Imports that are intentionally left alone

The mcp.types module moved to a standalone mcp-types distribution, but this is a no-op for projects that depend on mcp. The migration guide is explicit:

mcp.types is a permanent alias that mirrors mcp_types exactly. Keep importing through mcp, the package you actually depend on, rather than writing import mcp_types, which would reach past your declared dependency into a transitive one.

Rewriting those imports would introduce an undeclared dependency, so mcp-codemod never does. There is a test covering this.

Relationship to mcp-migration

mcp-migration detects behavioural hazards that a codemod cannot rewrite, such as in-memory state mutated inside tool handlers, session-id dependencies, and live server readiness. It is not a codemod. This tool is not a hazard detector. The two are complementary:

mcp-codemod .          # apply the mechanical changes
mcp-migration scan .   # then check for behavioural hazards

Limitations

• Coverage is the migration guide's "changes almost every project hits" table plus the removed-alias set. The full guide is 2,879 lines and this tool does not implement all of it.
• Rewrites are skipped in files that do not import mcp. A module that handles MCP types without importing from mcp will not be processed.
• Symbol renames are name-based. A local variable named Content in a file that also imports mcp would be renamed. Review the diff.
• Import order is left untouched. Use isort if you need it.

Development

pip install -e ".[dev]"
pytest

Author

Sanjay Keerthan (@8crsk)

License

MIT. See LICENSE.