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

Python · updated 2026-11-13

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.

Quick 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.

Run pip show mcp (or uv pip show mcp) to confirm the installed version is 2.x.
Replace from mcp.server.fastmcp import FastMCP with from mcp.server.mcpserver import MCPServer, Context.
Replace FastMCP("name") with MCPServer("name"), and ctx.fastmcp with ctx.mcp_server.
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.
Move host and port from the constructor to run(). Or pin mcp<2 in requirements.txt or pyproject.toml and migrate later.

python

# 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()

Fix it with your coding agent

Paste this into Claude Code, Cursor or Codex in the project that throws it. The agent reads this guide in plain text and applies the fix that matches your stack.

prompttext

Read https://runheed.com/errors/no-module-named-mcp-server-fastmcp.md and fix this error in this project.

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.

Other fixes

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 <name>"; 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'

Let your coding agent catch the next one

Python raises this while importing your modules, before runheed.init runs, so Runheed doesn't record it. What it does record is the exceptions your running server code throws (route handlers, server rendering, API errors and background jobs) with the stack trace and the breadcrumbs before them, and serves those errors to Claude Code, Cursor or any MCP client.

7-day trial, then $29/mo Try it in your agent on sample errors See the setupCancel any time from the billing portal

Setup for Python and FastAPI, Django or Flask, then have your agent fix and resolve it.

Building an MCP server? Track the errors your tools raise, in TypeScript or Python, so a failing tool shows up with its line instead of only in your users' client logs.

Related errors

More in MCP servers and clients

References: MCP Python SDK v2 migration guide: FastMCP renamed to MCPServer, mcp on PyPI (release history)

Spotted a mistake? Email hello@greatwork.company. About Runheed.