Install & Compatibility
Where this runs
tested against v3.4.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.9
✕ build_error
✕ build_error
138MB installed
● package 138MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FastMCP (v2 and v3 — same import path)
✓ from fastmcp import FastMCP
mcp = FastMCP('My Server')
@mcp.tool
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
mcp.run()
✗ from mcp.server.fastmcp import FastMCP
Use 'from fastmcp import FastMCP' for standalone package. 'from mcp.server.fastmcp import FastMCP' is FastMCP 1.0 bundled in the official mcp package — a different, older version.
Client
✓ from fastmcp import Client
async with Client('http://localhost:8000/mcp') as client:
tools = await client.list_tools()
result = await client.call_tool('add', {'a': 1, 'b': 2})
✗ from fastmcp import FastMCPClient
Client class replaces any earlier transport-specific client patterns. Handles transport negotiation automatically.
Decorators derive tool name, description, and JSON schema from function signature and docstring automatically. mcp.run() defaults to stdio for local use; pass transport='http' for remote deployments.
# Server
from fastmcp import FastMCP
mcp = FastMCP('Demo')
@mcp.tool
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
@mcp.resource('data://{name}')
def get_data(name: str) -> str:
"""Fetch named data"""
return f'Data for {name}'
@mcp.prompt
def review(code: str) -> str:
return f'Review this code:\n{code}'
if __name__ == '__main__':
mcp.run() # stdio by default
# mcp.run(transport='http', host='0.0.0.0', port=8000) # remote
# ---
# Client
import asyncio
from fastmcp import Client
async def main():
async with Client('http://localhost:8000/mcp') as client:
tools = await client.list_tools()
result = await client.call_tool('add', {'a': 1, 'b': 2})
print(result)
asyncio.run(main())
# ---
# CLI usage
# fastmcp list http://localhost:8000/mcp # list tools on any server
# fastmcp call http://localhost:8000/mcp add a=1 b=2 # call a tool
# fastmcp discover # find all locally configured servers
Debug
Known issues
breakingv3.0 (February 2026) is a major breaking rewrite from v2.x. Anyone not pinning fastmcp was auto-upgraded to v3.0 on pip install. Major changes: provider architecture replaces direct component registration, ctx.set_state()/ctx.get_state() are now async, StreamableHttpTransport replaces older HTTP transport classes, auth providers no longer auto-load config.fixPin to fastmcp<3 for v2 stability while migrating. See gofastmcp.com/development/upgrade-guide for the v2→v3 upgrade guide and copyable LLM migration prompt.
affects: v2.x code migrating to v3
breakingIn v3, @mcp.tool decorator returns the original function unchanged (so decorated functions remain directly callable). In v2.x, @mcp.tool returned a FunctionTool object. Code accessing .name, .description, or other FunctionTool attributes on the decorated result will break.fixRemove any attribute access on decorated functions. Set FASTMCP_DECORATOR_MODE=object temporarily for compatibility (deprecated).
affects: v2.x → v3 migration
breakingTransport config (host, port) must be passed to mcp.run(), not the FastMCP() constructor. Passing them to the constructor raises TypeError.fixReplace FastMCP('server', host='0.0.0.0', port=8080) with FastMCP('server') and mcp.run(transport='http', host='0.0.0.0', port=8080). affects: v2+ (enforced strictly in v3)
breakingfastmcp.server.auth module (introduced v2.12.0) is explicitly exempt from semantic versioning stability guarantees and has breaking changes on minor versions. Auth API changed significantly in v3.fixPin to an exact fastmcp version if using auth in production. Do not rely on auth API stability across minor versions.
affects: v2.12+ auth users
breakingGitHub repository moved from jlowin/fastmcp to PrefectHQ/fastmcp with v3.0. Old GitHub links forward automatically. PyPI package name, import paths, and CLI commands are unchanged.fixUpdate bookmarks and CI checkout references from jlowin/fastmcp to PrefectHQ/fastmcp.
affects: v3.0+
gotchafastmcp includes the mcp package as a dependency — installing both separately can cause version conflicts if mcp is pinned independently. fastmcp pins its compatible mcp version internally.fixIf using fastmcp, do not independently pin mcp in requirements. Let fastmcp manage the mcp dependency version.
affects: all
gotchaMinor versions may contain breaking changes (explicitly documented in release policy). 'Semantic versioning is pragmatic' — do not assume minor bumps are safe without checking release notes.fixPin to exact version in production: fastmcp==3.0.2. For development use ~=3.0 to get patches only.
affects: all
gotchafastmcp and the mcp SDK's bundled FastMCP 1.0 (from mcp.server.fastmcp) have the same class name but different behavior. Mixing imports in one project causes silent behavioral differences.fixUse only one: either 'from fastmcp import FastMCP' (standalone) or 'from mcp.server.fastmcp import FastMCP' (bundled v1). Never mix both in one project.
affects: all
gotchaCVE-2026-24486 (python-multipart) and CVE-2026-0994 (protobuf) were patched in fastmcp 3.0.2. Earlier 3.x and 2.x versions are vulnerable.fixUpgrade to fastmcp>=3.0.2.
affects: <3.0.2
breakingfastmcp requires Python 3.10 or newer. Attempting to install fastmcp in an environment with an older Python version (e.g., Python 3.9) will result in pip being unable to find a compatible distribution.fixUpgrade your Python environment to version 3.10 or newer to install fastmcp.
affects: all
breakingfastmcp v2.x (e.g., 2.14.6) depends on pydocket (e.g., 0.18.2). pydocket 0.18.2 requires `fakeredis>=2.32.1` but its internal code attempts to import `FakeConnection` from `fakeredis.aioredis`, which was removed in `fakeredis 2.32.1` and renamed to `FakeRedisConnection`. This leads to an ImportError, making fastmcp v2.x unusable with `fakeredis>=2.32.1`.fixExplicitly pin `fakeredis<2.32.1` in your requirements to ensure compatibility with pydocket in fastmcp v2.x. Alternatively, upgrade to fastmcp v3.x, which has a different dependency structure and is not affected by this issue.
affects: fastmcp v2.x (specifically when using pydocket versions incompatible with fakeredis>=2.32.1, like pydocket-0.18.2)
Upgrade
Version history
3.4.7latest on PyPI · released Aug 10, 2026
Audit
Dependencies
mcprequiredOfficial MCP SDK bundled as a dependency. fastmcp includes mcp — no need to install separately.
httpxrequiredHTTP client for streamable-http transport. Pinned <1.0 in fastmcp.
pydanticrequiredSchema generation from type hints for tool input/output validation.