ScreenshotNeo
Sign in Get a free key

BlogEngineering

How to Import FastMCP from mcp.server.fastmcp

Use the FastMCP import for MCP Python SDK v1, or switch to MCPServer from mcp.server in SDK v2.

By the ScreenshotNeo team1 October 20265 min read

For MCP Python SDK v1, use:

from mcp.server.fastmcp import FastMCP

For SDK v2, that module was removed. Use the renamed class and module:

from mcp.server import MCPServer

If from mcp.server.fastmcp import FastMCP raises ModuleNotFoundError, check the version installed by your dependency or lockfile. An unpinned pip install mcp now resolves to the stable 2.x line, so new projects commonly need the v2 import. The official MCP Python SDK repository and its v2 migration documentation describe this module and class rename.

Which import should you use?

Installed SDK Import Use when
v1 from mcp.server.fastmcp import FastMCP Your project is pinned to the v1 API.
v2 from mcp.server import MCPServer You use the current stable 2.x API.

The old path is removed in newer v2 releases; it is not just deprecated. Do not combine a v1 constructor or examples with a v2 import.

1. Check the version before changing code

Run these commands from the same virtual environment that starts your application:

python -m pip show mcp
python -m pip freeze | python -c "import sys; print([line for line in sys.stdin if line.lower().startswith('mcp==')])"

You can also inspect the resolved version in Python:

from importlib.metadata import version

print(version("mcp"))

Read the major number. A version beginning with 1. uses FastMCP; a version beginning with 2. uses MCPServer.

2. Use the v1 FastMCP import

If your dependency is intentionally on MCP SDK v1, the title’s import is correct:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("example")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

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

Pin the major version so a future install does not silently move this code to v2:

python -m pip install "mcp<2"
# requirements.txt
mcp>=1,<2

3. Use the v2 MCPServer import

For SDK v2, replace both the module and class name:

from mcp.server import MCPServer

server = MCPServer("example")

@server.tool()
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

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

Use the v2 migration guide for any additional constructor or transport changes in your application. A v1 snippet can fail even after changing only the import if it relies on the old class surface.

4. Support both majors deliberately

A compatibility import can help a library that explicitly supports both SDK majors:

try:
    from mcp.server import MCPServer
except ModuleNotFoundError:
    from mcp.server.fastmcp import FastMCP as MCPServer

server = MCPServer("compatible-example")

@server.tool()
def health() -> str:
    return "ok"

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

This fallback handles the module rename, but it does not guarantee that constructors, decorators, transports or lifecycle methods are identical. Declare the supported range, test every major version in CI, and keep separate examples when APIs differ.

# pyproject.toml example
[project]
dependencies = [
  "mcp>=1,<3"
]

# Better for an application that has chosen v2:
# "mcp>=2,<3"

5. Fix the common ModuleNotFoundError

Error: No module named mcp.server.fastmcp

Cause: You installed SDK v2, where the v1 module was removed.

Fix: Change the import to from mcp.server import MCPServer, then update the class name and any v1-only API calls. Alternatively, pin mcp<2 if the project must remain on v1.

Error: No module named mcp

Cause: The package is not installed in the active environment, or your editor uses a different interpreter.

Fix:

python -m pip install mcp
python -c "import mcp; print(mcp.__file__)"

Choose that same interpreter in your IDE and in the process manager that launches the server.

Error after changing only the import

Cause: The v2 migration changes the server class and may change surrounding APIs. A v1 constructor or decorator can still be present.

Fix: Update the complete example for one major version. Do not mix FastMCP documentation with MCPServer code.

It works locally but fails in CI

Cause: CI resolved a different major version because the dependency was unpinned or the lockfile was not installed.

Fix: Commit the lockfile, install from it in CI, and print importlib.metadata.version("mcp") during diagnostics.

Migration checklist

  1. Print the installed mcp version.
  2. Choose either the v1 or v2 API surface.
  3. For v1, import FastMCP from mcp.server.fastmcp.
  4. For v2, import MCPServer from mcp.server.
  5. Update the class name, constructors and decorators together.
  6. Pin the supported major version in project metadata.
  7. Run the server and a tool call in a clean environment.
  8. If supporting both, test both majors instead of relying only on the fallback import.

Performance, reliability and dependency-cost notes

The import choice itself has negligible runtime cost. Reliability comes from resolving the same dependency version in development, CI and production. Pinning a major version prevents an unplanned breaking migration; a lockfile also makes rebuilds reproducible. Supporting both majors increases maintenance cost because each API surface needs compatibility tests and documentation.

Keep the compatibility branch narrow and fail with a clear startup message if neither import exists. Do not catch every exception around the import: hiding unrelated import errors makes diagnosis harder.

Or skip the browser setup

If your MCP project needs website images for documentation, evaluation or agent workflows, ScreenshotNeo provides a screenshot API and MCP server. One request returns a PNG, JPEG, WebP or PDF. See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups and chat widgets are removed before the shot. Bot checks, blank pages and failed loads are never billed, and response headers identify the page verdict and billing result. Its MCP server includes take_screenshot, get_page_info and capture_pdf for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account.

FAQ

Is FastMCP still available in SDK v2?

The v1 module path is removed in newer v2 releases. Use MCPServer from mcp.server.

Should I leave the import unpinned?

Pin a major version for applications. Unpinned installs can resolve a newer major with a different import and API surface.

Can one package support v1 and v2?

Yes, with guarded imports and version-specific tests. The import fallback alone does not prove that the rest of the code is compatible.

Why does my editor underline the import while the script runs?

The editor may use a different Python interpreter or virtual environment. Select the environment where python -m pip show mcp reports the package.

Keep reading