Fix pages / MCP Python SDK

MCP Python SDK: "No module named 'mcp.server.fastmcp'"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    from mcp.server.fastmcp import FastMCP
  File "/opt/mcp-2.3.0/lib/python3.13/site-packages/mcp/server/fastmcp.py", line 16, in <module>
    raise ModuleNotFoundError(_MESSAGE, name=__name__)
ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed; see the migration guide at https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver or pin 'mcp<2' to keep running v1 code.

Tool: Model Context Protocol Python SDK (mcp, mcp-types). Versions: Affected: 2.0.0 and later; last version without this error: 1.30.0; we reproduced it on 1.30.0, 2.0.0, 2.3.0. Exit code 1.

Cause: MCP Python SDK 2.0 (released 2026-07-28) replaced the FastMCP framework class with mcp.server.mcpserver.MCPServer, removing the mcp.server.fastmcp module entirely.

Fix: Import MCPServer from mcp.server.mcpserver (or pin mcp>=1.28,<2 to remain on v1.x).

# migrate to MCP Python SDK 2.x:
# replace: from mcp.server.fastmcp import FastMCP
from mcp.server.mcpserver import MCPServer
mcp = MCPServer("my-server")

# or support both 1.x and 2.x during migration:
try:
    from mcp.server.mcpserver import MCPServer as FastMCP
except ModuleNotFoundError:
    from mcp.server.fastmcp import FastMCP

# or stay on the v1.x maintenance branch:
pip install "mcp>=1.28,<2"

In v2, all submodules under mcp.server.fastmcp were moved to mcp.server.mcpserver with the same structure (e.g. Image and Audio are now exported from mcp.server.mcpserver). In release 2.0.0, importing the removed module produced a bare ModuleNotFoundError: No module named 'mcp.server.fastmcp'; releases 2.0.1 and 2.1.1 added a stub module raising a custom message linking directly to the migration guide.

The same cause also prints:

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

Last verified 2026-10-10 (1.30.0, 2.0.0, 2.3.0). Page updated . Also as Markdown and JSON.

How did we reproduce the MCP Python SDK error?

A fresh Debian 13 VM from bin/sandbox-run (Python 3.13, root, online, no credentials needed), destroyed after the run. Run on . Failing command: python3 -c "from mcp.server.fastmcp import FastMCP".

Before (v1.x): FastMCP imports and initializes without error (MCP Python SDK 1.30.0):

$ python3 -c "from mcp.server.fastmcp import FastMCP; mcp = FastMCP('demo'); print(f'FastMCP initialized: {mcp.name}')"
FastMCP initialized: demo
# exit 0

After (2.0.0): FastMCP removed, raises bare ModuleNotFoundError (MCP Python SDK 2.0.0):

$ python3 -c "from mcp.server.fastmcp import FastMCP"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    from mcp.server.fastmcp import FastMCP
ModuleNotFoundError: No module named 'mcp.server.fastmcp'
# exit 1

Latest (2.3.0): fastmcp.py raises ModuleNotFoundError with migration pointer (MCP Python SDK 2.3.0):

$ python3 -c "from mcp.server.fastmcp import FastMCP"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
    from mcp.server.fastmcp import FastMCP
  File "/opt/mcp-2.3.0/lib/python3.13/site-packages/mcp/server/fastmcp.py", line 16, in <module>
    raise ModuleNotFoundError(_MESSAGE, name=__name__)
ModuleNotFoundError: No module named 'mcp.server.fastmcp'. This is mcp 2.x, where FastMCP was renamed to MCPServer (from mcp.server.mcpserver import MCPServer) and other APIs changed; see the migration guide at https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver or pin 'mcp<2' to keep running v1 code.
# exit 1

Fix verified: MCPServer imported and initialized successfully on 2.3.0 (MCP Python SDK 2.3.0):

$ python3 -c "from mcp.server.mcpserver import MCPServer; mcp = MCPServer('demo'); print(f'MCPServer initialized: {mcp.name}')"
MCPServer initialized: demo
# exit 0

Dual-compatibility shim on v1.30.0 (MCP Python SDK 1.30.0):

$ python3 -c "try:\n    from mcp.server.mcpserver import MCPServer as FastMCP\nexcept ModuleNotFoundError:\n    from mcp.server.fastmcp import FastMCP\nmcp = FastMCP('demo')\nprint(f'Dual-compatibility server initialized: {mcp.name}')"
Dual-compatibility server initialized: demo
# exit 0

Dual-compatibility shim on v2.3.0 (MCP Python SDK 2.3.0):

$ python3 -c "try:\n    from mcp.server.mcpserver import MCPServer as FastMCP\nexcept ModuleNotFoundError:\n    from mcp.server.fastmcp import FastMCP\nmcp = FastMCP('demo')\nprint(f'Dual-compatibility server initialized: {mcp.name}')"
Dual-compatibility server initialized: demo
# exit 0

Why does MCP Python SDK print this error?

In MCP Python SDK 2.0.0 (shipped 2026-07-28), FastMCP was renamed to MCPServer to reflect its role as the primary server interface; Pull Request #3388 (merged 2026-08-25, released in 2.1.1 and backported to 2.0.1 in PR #3393) added a stub module at src/mcp/server/fastmcp.py that raises an explicit ModuleNotFoundError pointing developers directly to the migration guide. (MCP Python SDK Migration Guide: FastMCP renamed to MCPServer)

Related MCP Python SDK fixes and pages

Sources

Last verified: 2026-10-10.