Back to Details

fastmcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

FastMCP - Build MCP Servers in Python

FastMCP - 用Python构建MCP服务器

FastMCP is a Python framework for building Model Context Protocol (MCP) servers that expose tools, resources, and prompts to Large Language Models like Claude.
FastMCP 是一款Python框架，用于构建模型上下文协议（MCP）服务器，向Claude等大语言模型暴露工具、资源和提示词。

Quick Start

快速开始

Installation

安装

bash
pip install fastmcp
bash
pip install fastmcp

or: uv pip install fastmcp

or: uv pip install fastmcp

undefined
undefined

Minimal Server

最简服务器

python
from fastmcp import FastMCP
python
from fastmcp import FastMCP

MUST be at module level for FastMCP Cloud

必须在模块级别定义，以适配FastMCP Cloud

mcp = FastMCP("My Server")
@mcp.tool() async def hello(name: str) -> str: """Say hello to someone.""" return f"Hello, {name}!"
if name == "main": mcp.run()

**Run:**
```bash
python server.py              # Local development
fastmcp dev server.py         # With FastMCP CLI
python server.py --transport http --port 8000  # HTTP mode
Copy-Paste Template: See 
templates/basic-server.py
mcp = FastMCP("My Server")
@mcp.tool() async def hello(name: str) -> str: """向某人打招呼。""" return f"Hello, {name}!"
if name == "main": mcp.run()

**运行：**
```bash
python server.py              # 本地开发
fastmcp dev server.py         # 使用FastMCP CLI
python server.py --transport http --port 8000  # HTTP模式
复制粘贴模板：查看
templates/basic-server.py

Core Concepts

核心概念

Tools

工具

Functions that LLMs can call:
python
@mcp.tool()
def calculate(operation: str, a: float, b: float) -> float:
    """Perform mathematical operations."""
    operations = {
        "add": lambda x, y: x + y,
        "subtract": lambda x, y: x - y,
        "multiply": lambda x, y: x * y,
        "divide": lambda x, y: x / y if y != 0 else None
    }
    return operations.get(operation, lambda x, y: None)(a, b)
Best Practices:
  • Clear, descriptive function names
  • Comprehensive docstrings (LLMs read these!)
  • Strong type hints (Pydantic validates automatically)
  • Return structured data (dicts/lists)
  • Handle errors gracefully
大语言模型可调用的函数：
python
@mcp.tool()
def calculate(operation: str, a: float, b: float) -> float:
    """执行数学运算。"""
    operations = {
        "add": lambda x, y: x + y,
        "subtract": lambda x, y: x - y,
        "multiply": lambda x, y: x * y,
        "divide": lambda x, y: x / y if y != 0 else None
    }
    return operations.get(operation, lambda x, y: None)(a, b)
最佳实践：
  • 清晰、描述性的函数名称
  • 全面的文档字符串（大语言模型会读取这些内容！）
  • 强类型提示（Pydantic会自动验证）
  • 返回结构化数据（字典/列表）
  • 优雅处理错误

Resources

资源

Expose static or dynamic data:
python
@mcp.resource("data://config")
def get_config() -> dict:
    """Provide application configuration."""
    return {"version": "1.0.0", "features": ["auth", "api"]}
暴露静态或动态数据：
python
@mcp.resource("data://config")
def get_config() -> dict:
    """提供应用配置。"""
    return {"version": "1.0.0", "features": ["auth", "api"]}

Dynamic resource with parameters

带参数的动态资源

@mcp.resource("user://{user_id}/profile") async def get_user_profile(user_id: str) -> dict: """Get user profile by ID.""" return {"id": user_id, "name": f"User {user_id}"}

**URI Schemes**: `data://`, `file://`, `resource://`, `info://`, `api://`, or custom
@mcp.resource("user://{user_id}/profile") async def get_user_profile(user_id: str) -> dict: """根据ID获取用户资料。""" return {"id": user_id, "name": f"User {user_id}"}

**URI协议**：`data://`、`file://`、`resource://`、`info://`、`api://`或自定义协议

Prompts

提示词

Pre-configured prompts for LLMs:
python
@mcp.prompt("analyze")
def analyze_prompt(topic: str) -> str:
    """Generate analysis prompt."""
    return f"""Analyze {topic} considering:
    1. Current state
    2. Challenges
    3. Opportunities
    4. Recommendations"""
为大语言模型预配置的提示词：
python
@mcp.prompt("analyze")
def analyze_prompt(topic: str) -> str:
    """生成分析提示词。"""
    return f"""分析{topic}时请考虑：
    1. 当前状态
    2. 挑战
    3. 机遇
    4. 建议"""

Context Features

上下文特性

Progress Tracking:
python
from fastmcp import Context

@mcp.tool()
async def batch_process(items: list, context: Context) -> dict:
    """Process items with progress updates."""
    for i, item in enumerate(items):
        await context.report_progress(i + 1, len(items), f"Processing {item}")
        await process_item(item)
    return {"processed": len(items)}
User Input:
python
@mcp.tool()
async def confirm_action(action: str, context: Context) -> dict:
    """Perform action with user confirmation."""
    confirmed = await context.request_elicitation(
        prompt=f"Confirm {action}? (yes/no)",
        response_type=str
    )
    return {"confirmed": confirmed.lower() == "yes"}
进度跟踪：
python
from fastmcp import Context

@mcp.tool()
async def batch_process(items: list, context: Context) -> dict:
    """处理项目并更新进度。"""
    for i, item in enumerate(items):
        await context.report_progress(i + 1, len(items), f"Processing {item}")
        await process_item(item)
    return {"processed": len(items)}
用户输入：
python
@mcp.tool()
async def confirm_action(action: str, context: Context) -> dict:
    """获取用户确认后执行操作。"""
    confirmed = await context.request_elicitation(
        prompt=f"Confirm {action}? (yes/no)",
        response_type=str
    )
    return {"confirmed": confirmed.lower() == "yes"}

Storage Backends

存储后端

Choose storage based on deployment:
python
from key_value.stores import DiskStore, RedisStore
from key_value.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernet
根据部署场景选择存储方式：
python
from key_value.stores import DiskStore, RedisStore
from key_value.encryption import FernetEncryptionWrapper
from cryptography.fernet import Fernet

Memory (default) - Development only

内存存储（默认）- 仅用于开发

mcp = FastMCP("Dev Server")
mcp = FastMCP("Dev Server")

Disk - Single instance

磁盘存储 - 单实例部署

mcp = FastMCP( "Production Server", storage=FernetEncryptionWrapper( key_value=DiskStore(path="/var/lib/mcp/storage"), fernet=Fernet(os.getenv("STORAGE_ENCRYPTION_KEY")) ) )
mcp = FastMCP( "Production Server", storage=FernetEncryptionWrapper( key_value=DiskStore(path="/var/lib/mcp/storage"), fernet=Fernet(os.getenv("STORAGE_ENCRYPTION_KEY")) ) )

Redis - Multi-instance

Redis存储 - 多实例部署

mcp = FastMCP( "Production Server", storage=FernetEncryptionWrapper( key_value=RedisStore( host=os.getenv("REDIS_HOST"), password=os.getenv("REDIS_PASSWORD") ), fernet=Fernet(os.getenv("STORAGE_ENCRYPTION_KEY")) ) )
undefined
mcp = FastMCP( "Production Server", storage=FernetEncryptionWrapper( key_value=RedisStore( host=os.getenv("REDIS_HOST"), password=os.getenv("REDIS_PASSWORD") ), fernet=Fernet(os.getenv("STORAGE_ENCRYPTION_KEY")) ) )
undefined

Server Lifespans

服务器生命周期

Initialize resources on server startup:
python
from contextlib import asynccontextmanager

@asynccontextmanager
async def app_lifespan(server: FastMCP):
    """Runs ONCE when server starts (v2.13.0+)."""
    db = await Database.connect()
    print("Server starting")
    
    try:
        yield {"db": db}
    finally:
        await db.disconnect()
        print("Server stopping")

mcp = FastMCP("My Server", lifespan=app_lifespan)
Critical: v2.13.0+ lifespans run per-server (not per-session). For per-session logic, use middleware.
在服务器启动时初始化资源：
python
from contextlib import asynccontextmanager

@asynccontextmanager
async def app_lifespan(server: FastMCP):
    """服务器启动时运行一次（v2.13.0+）。"""
    db = await Database.connect()
    print("Server starting")
    
    try:
        yield {"db": db}
    finally:
        await db.disconnect()
        print("Server stopping")

mcp = FastMCP("My Server", lifespan=app_lifespan)
重要提示：v2.13.0+版本的生命周期是针对服务器实例运行一次（而非每个会话）。如需会话级逻辑，请使用中间件。

Middleware System

中间件系统

8 built-in middleware types:
python
from fastmcp.middleware import (
    LoggingMiddleware,
    TimingMiddleware,
    RateLimitingMiddleware,
    ResponseCachingMiddleware
)
8种内置中间件类型：
python
from fastmcp.middleware import (
    LoggingMiddleware,
    TimingMiddleware,
    RateLimitingMiddleware,
    ResponseCachingMiddleware
)

Order matters!

顺序很重要！

mcp.add_middleware(LoggingMiddleware()) mcp.add_middleware(TimingMiddleware()) mcp.add_middleware(RateLimitingMiddleware(max_requests=100, window_seconds=60)) mcp.add_middleware(ResponseCachingMiddleware(ttl_seconds=3600))

**Custom Middleware:**
```python
from fastmcp.middleware import BaseMiddleware

class CustomMiddleware(BaseMiddleware):
    async def on_call_tool(self, tool_name, arguments, context):
        print(f"Before: {tool_name}")
        result = await self.next(tool_name, arguments, context)  # MUST call next()
        print(f"After: {tool_name}")
        return result
mcp.add_middleware(LoggingMiddleware()) mcp.add_middleware(TimingMiddleware()) mcp.add_middleware(RateLimitingMiddleware(max_requests=100, window_seconds=60)) mcp.add_middleware(ResponseCachingMiddleware(ttl_seconds=3600))

**自定义中间件：**
```python
from fastmcp.middleware import BaseMiddleware

class CustomMiddleware(BaseMiddleware):
    async def on_call_tool(self, tool_name, arguments, context):
        print(f"Before: {tool_name}")
        result = await self.next(tool_name, arguments, context)  # 必须调用next()
        print(f"After: {tool_name}")
        return result

Server Composition

服务器组合

Import Server (static, one-time copy):
python
main_server.import_server(vendor_server)  # Static bundle
Mount Server (dynamic, runtime delegation):
python
main_server.mount(api_server, prefix="api")  # Changes appear immediately
导入服务器（静态，一次性复制）：
python
main_server.import_server(vendor_server)  # 静态打包
挂载服务器（动态，运行时委托）：
python
main_server.mount(api_server, prefix="api")  # 变更会立即生效

Cloud Deployment

云部署

FastMCP Cloud Requirements:
  1. Server MUST be at module level
  2. Use disk/Redis storage (not memory)
  3. No import-time execution
python
undefined
FastMCP Cloud要求：
  1. 服务器必须在模块级别定义
  2. 使用磁盘/Redis存储（而非内存）
  3. 禁止在导入时执行代码
python
undefined

✅ Cloud-ready pattern

✅ 符合云部署的模式

mcp = FastMCP("My Server") # Module level
@mcp.tool() async def my_tool(): pass
if name == "main": mcp.run()

**Deploy:**
```bash
fastmcp deploy server.py
mcp = FastMCP("My Server") # 模块级别
@mcp.tool() async def my_tool(): pass
if name == "main": mcp.run()

**部署命令：**
```bash
fastmcp deploy server.py

Top 5 Critical Errors

五大关键错误

1. Missing Server Object

1. 缺少服务器对象

Error: 
RuntimeError: No server object found at module level
Fix:
python
undefined
错误信息： 
RuntimeError: No server object found at module level
修复方案：
python
undefined

❌ WRONG

❌ 错误写法

def create_server(): return FastMCP("server")
def create_server(): return FastMCP("server")

✅ CORRECT

✅ 正确写法

mcp = FastMCP("server") # At module level
undefined
mcp = FastMCP("server") # 在模块级别定义
undefined

2. Async/Await Confusion

2. Async/Await混淆

Error: 
RuntimeError: no running event loop
Fix:
python
undefined
错误信息： 
RuntimeError: no running event loop
修复方案：
python
undefined

❌ WRONG: Sync function calling async

❌ 错误写法：同步函数调用异步代码

@mcp.tool() def bad_tool(): result = await async_function() # Error!
@mcp.tool() def bad_tool(): result = await async_function() # 错误！

✅ CORRECT: Async tool

✅ 正确写法：异步工具

@mcp.tool() async def good_tool(): result = await async_function() return result
undefined
@mcp.tool() async def good_tool(): result = await async_function() return result
undefined

3. Context Not Injected

3. 上下文未注入

Error: 
TypeError: missing 1 required positional argument: 'context'
Fix:
python
from fastmcp import Context
错误信息： 
TypeError: missing 1 required positional argument: 'context'
修复方案：
python
from fastmcp import Context

❌ WRONG: No type hint

❌ 错误写法：缺少类型提示

@mcp.tool() async def bad_tool(context): # Missing type! await context.report_progress(...)
@mcp.tool() async def bad_tool(context): # 缺少类型！ await context.report_progress(...)

✅ CORRECT: Proper type hint

✅ 正确写法：正确的类型提示

@mcp.tool() async def good_tool(context: Context): await context.report_progress(0, 100, "Starting")
undefined
@mcp.tool() async def good_tool(context: Context): await context.report_progress(0, 100, "Starting")
undefined

4. Storage Backend Not Configured

4. 存储后端未配置

Error: 
RuntimeError: OAuth tokens lost on restart
Fix: Use disk or Redis storage in production (see Storage Backends section above)
错误信息： 
RuntimeError: OAuth tokens lost on restart
修复方案： 生产环境使用磁盘或Redis存储（见上方存储后端章节）

5. Circular Import Errors

5. 循环导入错误

Error: 
ImportError: cannot import name 'X' from partially initialized module
Fix:
python
undefined
错误信息： 
ImportError: cannot import name 'X' from partially initialized module
修复方案：
python
undefined

❌ WRONG: Factory function creating circular dependency

❌ 错误写法：工厂函数导致循环依赖

shared/init.py

shared/init.py

def get_client(): from .api_client import APIClient # Circular! return APIClient()
def get_client(): from .api_client import APIClient # 循环依赖！ return APIClient()

✅ CORRECT: Direct imports

✅ 正确写法：直接导入

shared/init.py

shared/init.py

from .api_client import APIClient from .cache import CacheManager
from .api_client import APIClient from .cache import CacheManager

shared/monitoring.py

shared/monitoring.py

from .api_client import APIClient client = APIClient()

**See all 25 errors**: `references/error-catalog.md`
from .api_client import APIClient client = APIClient()

**查看全部25种错误**：`references/error-catalog.md`

Client Configuration

客户端配置

Claude Desktop

Claude Desktop

json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}
json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

Claude Code CLI

Claude Code CLI

json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}
json
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}

CLI Commands

CLI命令

bash
fastmcp dev server.py              # Development mode with hot reload
fastmcp run server.py              # Production mode
fastmcp deploy server.py           # Deploy to FastMCP Cloud
fastmcp test server.py             # Run tests
bash
fastmcp dev server.py              # 带热重载的开发模式
fastmcp run server.py              # 生产模式
fastmcp deploy server.py           # 部署到FastMCP Cloud
fastmcp test server.py             # 运行测试

Best Practices

最佳实践

  1. Server Structure: Keep module-level server, organize tools in separate files
  2. Type Hints: Use Pydantic models for complex validation
  3. Documentation: Write detailed docstrings (LLMs read them!)
  4. Error Handling: Catch and return structured errors
  5. Storage: Use encrypted disk/Redis in production
  6. Lifespans: Initialize connections once per server
  7. Middleware: Order matters (error handling → timing → logging → rate limiting → caching)
  8. Testing: Unit test tools with 
    FastMCP.test_tool()
  1. 服务器结构：保持模块级服务器定义，将工具组织在单独文件中
  2. 类型提示：使用Pydantic模型进行复杂验证
  3. 文档：编写详细的文档字符串（大语言模型会读取这些内容！）
  4. 错误处理：捕获并返回结构化错误
  5. 存储：生产环境使用加密磁盘/Redis存储
  6. 生命周期：每个服务器实例仅初始化一次连接
  7. 中间件：顺序很重要（错误处理 → 计时 → 日志 → 限流 → 缓存）
  8. 测试：使用
    FastMCP.test_tool()
    对工具进行单元测试

Bundled Resources

捆绑资源

References (
references/
):
  • cli-commands.md
    - Complete CLI command reference (dev, run, deploy, test)
  • cloud-deployment.md
    - FastMCP Cloud deployment guide with module-level requirements
  • common-errors.md
    - All 25 documented errors with solutions and prevention
  • context-features.md
    - Progress tracking, user input, and Context API patterns
  • error-catalog.md
    - Comprehensive error catalog with fixes
  • integration-patterns.md
    - Server composition (import/mount), OAuth Proxy, OpenAPI
  • production-patterns.md
    - Storage backends, lifespans, middleware, architecture patterns
Templates (
templates/
):
  • basic-server.py
    - Minimal MCP server with tools, resources, prompts
  • client-example.py
    - MCP client integration examples
  • api-client-pattern.py
    - API integration patterns
  • error-handling.py
    - Error handling best practices
  • openapi-integration.py
    - OpenAPI schema integration
  • prompts-examples.py
    - Prompt template patterns
  • resources-examples.py
    - Resource URI patterns and examples
  • tools-examples.py
    - Tool definition patterns
  • self-contained-server.py
    - Complete production-ready self-contained server
  • .env.example
    - Environment variables template
  • requirements.txt
    - Python dependencies
  • pyproject.toml
    - Python project configuration
参考文档（
references/
）：
  • cli-commands.md
    - 完整CLI命令参考（开发、运行、部署、测试）
  • cloud-deployment.md
    - FastMCP Cloud部署指南，含模块级要求
  • common-errors.md
    - 全部25种已记录错误及解决方案和预防措施
  • context-features.md
    - 进度跟踪、用户输入及Context API模式
  • error-catalog.md
    - 全面的错误目录及修复方案
  • integration-patterns.md
    - 服务器组合（导入/挂载）、OAuth代理、OpenAPI
  • production-patterns.md
    - 存储后端、生命周期、中间件、架构模式
模板（
templates/
）：
  • basic-server.py
    - 包含工具、资源、提示词的最简MCP服务器
  • client-example.py
    - MCP客户端集成示例
  • api-client-pattern.py
    - API集成模式
  • error-handling.py
    - 错误处理最佳实践
  • openapi-integration.py
    - OpenAPI schema集成
  • prompts-examples.py
    - 提示词模板模式
  • resources-examples.py
    - 资源URI模式及示例
  • tools-examples.py
    - 工具定义模式
  • self-contained-server.py
    - 完整的生产级独立服务器
  • .env.example
    - 环境变量模板
  • requirements.txt
    - Python依赖
  • pyproject.toml
    - Python项目配置

Dependencies

依赖项

json
{
  "dependencies": {
    "fastmcp": ">=2.13.0",
    "pydantic": ">=2.0.0"
  },
  "optionalDependencies": {
    "py-key-value-aio": ">=0.1.0",  // For storage backends
    "cryptography": ">=41.0.0",     // For encryption
    "redis": ">=5.0.0"              // For Redis storage
  }
}
json
{
  "dependencies": {
    "fastmcp": ">=2.13.0",
    "pydantic": ">=2.0.0"
  },
  "optionalDependencies": {
    "py-key-value-aio": ">=0.1.0",  // 用于存储后端
    "cryptography": ">=41.0.0",     // 用于加密
    "redis": ">=5.0.0"              // 用于Redis存储
  }
}

Official Documentation

官方文档

Verification Checklist

验证清单

  • FastMCP installed (
    fastmcp>=2.13.0
    )
  • Server object at module level
  • Tool docstrings comprehensive
  • Context type hints for context parameters
  • Resource URIs have schemes
  • Storage backend configured (production)
  • Lifespan pattern correct (v2.13.0+)
  • Middleware order logical
  • Client configuration tested
  • Production deployment successful
Token Savings: 90-95% vs learning from scratch Errors Prevented: 25 documented issues Production Tested: ✅ Multiple deployments
  • 已安装FastMCP（
    fastmcp>=2.13.0
    ）
  • 服务器对象在模块级别定义
  • 工具文档字符串全面
  • 上下文参数带有类型提示
  • 资源URI包含协议
  • 已配置存储后端（生产环境）
  • 生命周期模式正确（v2.13.0+）
  • 中间件顺序合理
  • 客户端配置已测试
  • 生产部署成功
节省时间：相比从零开始学习，可节省90-95%的时间 避免错误：可预防25种已记录的问题 生产验证：✅ 已完成多次部署