Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 2 min read

How to fix "No module named 'mcp.server.fastmcp'"

Originally published at runheed.com. Raised when Python imports your MCP server with mcp 2.0 or later installed (2.0 shipped on July 28, 2026; 2.3.0 is current). The class FastMCP is now MCPServer and every module under

Originally published at runheed.com.

Raised when Python imports your MCP server with mcp 2.0 or later installed (2.0 shipped on July 28, 2026; 2.3.0 is current). The class FastMCP is now MCPServer and every module under mcp.server.fastmcp moved to mcp.server.mcpserver. The SDK raises this ModuleNotFoundError with a hint that names the new import and the migration guide. A server run by Claude Desktop, Claude Code or Cursor dies at startup, so the client only reports that the connection closed.

Traceback (most recent call last):
  File "server.py", line 2, in <module>
    from mcp.server.fastmcp import FastMCP
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.

The fix

Change the import to from mcp.server.mcpserver import MCPServer and build the server with MCPServer("name"). If you are not ready to migrate, pin the dependency to mcp<2 so a fresh install doesn't pick up 2.x. Note that the separate fastmcp package (from fastmcp import FastMCP) is a different project and is not affected.

  1. Run pip show mcp (or uv pip show mcp) to confirm the installed version is 2.x.
  2. Replace from mcp.server.fastmcp import FastMCP with from mcp.server.mcpserver import MCPServer, Context.
  3. Replace FastMCP("name") with MCPServer("name"), and ctx.fastmcp with ctx.mcp_server.
  4. Pass everything after the name by keyword: 2.x added title and description to the positional parameters, so a positional instructions string silently becomes the title.
  5. Move host and port from the constructor to run(). Or pin mcp<2 in requirements.txt or pyproject.toml and migrate later.
# mcp 1.x
# from mcp.server.fastmcp import FastMCP
# mcp = FastMCP("orders", "You look up orders.")

# mcp 2.x
from mcp.server.mcpserver import MCPServer

mcp = MCPServer("orders", instructions="You look up orders.")

@mcp.tool()
def get_order(order_id: str) -> str:
    """Look up an order."""
    return lookup(order_id)

if __name__ == "__main__":
    mcp.run()

Why it happens

  • An unpinned dependency picked up mcp 2.x. requirements.txt or pyproject.toml lists mcp with no upper bound, so a new environment, a CI build or uvx installs the latest major version.
  • Tutorial or template code written for 1.x. Most published examples still import FastMCP from mcp.server.fastmcp.
  • Submodule imports. Imports such as mcp.server.fastmcp.prompts or mcp.server.fastmcp.utilities fail the same way; they live under mcp.server.mcpserver now.

Also worth knowing

  • MCP_* environment variables and .env files are no longer read by MCPServer in 2.x: pass those settings explicitly.
  • A server that crashes on import is reported by the client as MCP error -32000: Connection closed (from a Python client: MCPError: Connection closed inside an ExceptionGroup).
  • After the upgrade, a tool that raises reaches the client only as "Error executing tool "; the cause is logged on the server.

Same error, other wording

  • ModuleNotFoundError: No module named 'mcp.server.fastmcp.prompts'
  • ImportError: cannot import name 'FastMCP' from 'mcp.server'

Sources

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.