{
  "slug": "mcp-python-no-module-fastmcp",
  "url": "https://insidetheloop.dev/fixes/mcp-python-no-module-fastmcp",
  "markdown_url": "https://insidetheloop.dev/fixes/mcp-python-no-module-fastmcp.md",
  "title": "MCP Python SDK: \"No module named 'mcp.server.fastmcp'\"",
  "description": "MCP Python SDK 2.0 renamed FastMCP to MCPServer. Update imports to from mcp.server.mcpserver import MCPServer, or pin mcp>=1.28,<2.",
  "tool": {
    "id": "mcp-python-sdk",
    "name": "MCP Python SDK",
    "long_name": "Model Context Protocol Python SDK (mcp, mcp-types)",
    "url": "https://insidetheloop.dev/tools/mcp-python-sdk",
    "latest_version": "2.3.0"
  },
  "error": "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.",
  "variants": [
    "ModuleNotFoundError: No module named 'mcp.server.fastmcp'"
  ],
  "output": "Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n    from mcp.server.fastmcp import FastMCP\n  File \"/opt/mcp-2.3.0/lib/python3.13/site-packages/mcp/server/fastmcp.py\", line 16, in <module>\n    raise ModuleNotFoundError(_MESSAGE, name=__name__)\nModuleNotFoundError: 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_code": 1,
  "command": "python3 -c \"from mcp.server.fastmcp import FastMCP\"",
  "versions": {
    "affected": "2.0.0 and later",
    "first_bad": "2.0.0",
    "last_good": "1.30.0",
    "fixed_in": null,
    "tested": [
      "1.30.0",
      "2.0.0",
      "2.3.0"
    ]
  },
  "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": {
    "summary": "Import `MCPServer` from `mcp.server.mcpserver` (or pin `mcp>=1.28,<2` to remain on v1.x).",
    "commands": [
      "# 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\""
    ],
    "note": "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."
  },
  "reproduction": {
    "ran_at": "2026-10-10T12:19:57Z",
    "environment": "A fresh Debian 13 VM from `bin/sandbox-run` (Python 3.13, root, online, no credentials needed), destroyed after the run.",
    "steps": [
      {
        "label": "Before (v1.x): FastMCP imports and initializes without error",
        "version": "1.30.0",
        "command": "python3 -c \"from mcp.server.fastmcp import FastMCP; mcp = FastMCP('demo'); print(f'FastMCP initialized: {mcp.name}')\"",
        "output": "FastMCP initialized: demo",
        "exit": 0
      },
      {
        "label": "After (2.0.0): FastMCP removed, raises bare ModuleNotFoundError",
        "version": "2.0.0",
        "command": "python3 -c \"from mcp.server.fastmcp import FastMCP\"",
        "output": "Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n    from mcp.server.fastmcp import FastMCP\nModuleNotFoundError: No module named 'mcp.server.fastmcp'",
        "exit": 1
      },
      {
        "label": "Latest (2.3.0): fastmcp.py raises ModuleNotFoundError with migration pointer",
        "version": "2.3.0",
        "command": "python3 -c \"from mcp.server.fastmcp import FastMCP\"",
        "output": "Traceback (most recent call last):\n  File \"<string>\", line 1, in <module>\n    from mcp.server.fastmcp import FastMCP\n  File \"/opt/mcp-2.3.0/lib/python3.13/site-packages/mcp/server/fastmcp.py\", line 16, in <module>\n    raise ModuleNotFoundError(_MESSAGE, name=__name__)\nModuleNotFoundError: 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
      },
      {
        "label": "Fix verified: MCPServer imported and initialized successfully on 2.3.0",
        "version": "2.3.0",
        "command": "python3 -c \"from mcp.server.mcpserver import MCPServer; mcp = MCPServer('demo'); print(f'MCPServer initialized: {mcp.name}')\"",
        "output": "MCPServer initialized: demo",
        "exit": 0
      },
      {
        "label": "Dual-compatibility shim on v1.30.0",
        "version": "1.30.0",
        "command": "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}')\"",
        "output": "Dual-compatibility server initialized: demo",
        "exit": 0
      },
      {
        "label": "Dual-compatibility shim on v2.3.0",
        "version": "2.3.0",
        "command": "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}')\"",
        "output": "Dual-compatibility server initialized: demo",
        "exit": 0
      }
    ]
  },
  "why": {
    "text": "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.",
    "url": "https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver",
    "source": "MCP Python SDK Migration Guide: FastMCP renamed to MCPServer"
  },
  "tool_page": "https://insidetheloop.dev/tools/mcp-python-sdk#gotcha-from-mcp-server-fastmcp-import-fastmcp-raises-modulenotfounderror-in-2-x",
  "related": [],
  "sources": [
    {
      "title": "MCP Python SDK Migration Guide: FastMCP renamed to MCPServer",
      "url": "https://py.sdk.modelcontextprotocol.io/v2/migration/#fastmcp-renamed-to-mcpserver",
      "read": "2026-10-10"
    },
    {
      "title": "Point imports of mcp.server.fastmcp at the migration guide (PR #3388)",
      "url": "https://github.com/modelcontextprotocol/python-sdk/pull/3388",
      "read": "2026-10-10"
    },
    {
      "title": "Backport fastmcp migration pointer to v2.0.1 (PR #3393)",
      "url": "https://github.com/modelcontextprotocol/python-sdk/pull/3393",
      "read": "2026-10-10"
    },
    {
      "title": "MCP Python SDK v2.3.0 release notes",
      "url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0",
      "read": "2026-10-10"
    },
    {
      "title": "MCP Python SDK v2.0.0 stable release",
      "url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.0.0",
      "read": "2026-10-10"
    },
    {
      "title": "MCP Python SDK v1.30.0 release",
      "url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.30.0",
      "read": "2026-10-10"
    },
    {
      "title": "PyPI mcp package release history and download statistics",
      "url": "https://pypi.org/project/mcp/",
      "read": "2026-10-10"
    }
  ],
  "date_published": "2026-10-10T12:20:31Z",
  "date_modified": "2026-10-10T12:26:06Z",
  "verified": {
    "date": "2026-10-10",
    "versions": [
      "1.30.0",
      "2.0.0",
      "2.3.0"
    ]
  }
}