FastMCP 开发 MCP Server 完全实战指南
🚀 FastMCP 开发 MCP Server 完全实战指南
一份从零到生产部署的 FastMCP 教程,让初学者一行一行跟着写就能上手
📖 写在前面
如果你已经了解什么是 MCP（Model Context Protocol），那一定听说过FastMCP——它是目前 Python 开发 MCP Server 最流行的框架,70% 的 MCP Server 都用它构建,日下载量超过 100 万次。
为什么选 FastMCP？
官方 Python SDK 写一个 MCP Server 大概需要这样：
# 用官方 SDK 的繁琐写法（约 30 行） server = Server({"name": "my-server", "version": "1.0.0"}, {...}) server.set_request_handler("tools/list", async_def_func) server.set_request_handler("tools/call", another_async_def_func) # ... 还要手动写 JSON Schema、参数验证、错误处理而 FastMCP 写一个 MCP Server 长这样：
# 用 FastMCP 的优雅写法（5 行搞定） from fastmcp import FastMCP mcp = FastMCP("My Server") @mcp.tool def add(a: int, b: int) -> int: """加两个数""" return a + b mcp.run()优雅、Pythonic、生产可用——这就是 FastMCP 的魅力。
读完这份文档,你将：
- 从零搭建一个完整的 MCP Server
- 掌握 Tools、Resources、Prompts 三大核心组件
- 学会调试、测试、部署到生产环境
- 理解中间件、认证、代理等高级功能
- 把你的 Server 接入 Claude Desktop、Cursor、VS Code
🎯 第一章：FastMCP 是什么？
1.1 一句话介绍
FastMCP是一个用装饰器（Decorator）风格构建 MCP Server 和 Client 的 Python 框架,由 Jeremiah Lowin 创建,现由 Prefect 团队维护。
1.2 FastMCP 1.0 vs 2.0 vs 3.0
FastMCP 经历了三个重要版本：
| 版本 | 时间 | 说明 |
|---|---|---|
| FastMCP 1.0 | 2024 | 已被并入官方 MCP Python SDK,即mcp.server.fastmcp |
| FastMCP 2.0 | 2025 | 独立维护的版本,加入认证、代理、中间件等高级功能 |
| FastMCP 3.0 | 2026 年 2 月 | 重构核心架构,引入 Provider/Transform 两大原语 |
目前推荐使用 FastMCP 3.x（PyPI 包名就叫fastmcp）。
1.3 FastMCP 三大支柱
┌────────────────────────────────────────────────────┐ │ FastMCP 三大支柱 │ ├──────────────┬──────────────┬─────────────────────┤ │ Servers │ Clients │ Apps │ │ │ │ │ │ 把 Python │ 连接任意 MCP │ 给工具加上交互式 UI │ │ 函数包装成 │ Server,本地 │ 直接渲染在对话框中 │ │ MCP 工具/ │ 或远程 │ │ │ 资源/提示 │ │ │ └──────────────┴──────────────┴─────────────────────┘本教程主要聚焦Servers部分——这是最常用的能力。
⚙️ 第二章：环境准备
2.1 系统要求
- Python 3.10+（推荐 3.12+,性能更好）
- 包管理器：
uv（强烈推荐）或pip
2.2 安装 uv（推荐）
uv是新一代 Python 包管理器,比 pip 快 10-100 倍,FastMCP 的 CLI 工具需要 uv。
# macOS / Linux curl -LsSf https://astral.sh/uv/install.sh | sh # Windows (PowerShell) powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # 或用 pip 安装 pip install uv # 验证 uv --version2.3 创建项目
# 创建项目目录 mkdir my-mcp-server && cd my-mcp-server # 初始化项目（生成 pyproject.toml） uv init # 添加 FastMCP 依赖 uv add fastmcp如果不用 uv,直接：
pip install fastmcp2.4 验证安装
# 创建一个测试文件 test_install.py from fastmcp import FastMCP print("FastMCP 安装成功!")python test_install.py # 输出: FastMCP 安装成功!🌟 第三章：Hello World——5 行代码起步
3.1 第一个 MCP Server
创建文件server.py：
from fastmcp import FastMCP # 创建 Server 实例 mcp = FastMCP("Demo Server 🚀") # 注册一个工具 @mcp.tool def add(a: int, b: int) -> int: """将两个数字相加""" return a + b # 启动 Server if __name__ == "__main__": mcp.run()3.2 运行 Server
python server.pyServer 启动后,会等待客户端连接（默认通过 stdio 传输）。
3.3 这 5 行代码做了什么？
让我们逐行拆解：
from fastmcp import FastMCP导入 FastMCP 主类。
mcp = FastMCP("Demo Server 🚀")创建一个 Server 实例,名字叫 "Demo Server 🚀"。这个名字会显示在 AI 客户端的 UI 中。
@mcp.tool def add(a: int, b: int) -> int: """将两个数字相加""" return a + b
@mcp.tool装饰器是关键!它自动做了三件事：
- 工具名：使用函数名
add- 工具描述：使用 docstring
"将两个数字相加"- 参数 Schema：根据类型注解
a: int, b: int生成 JSON Schema这就是 FastMCP 的核心理念：写 Python,不写协议样板。
mcp.run()启动 Server,默认使用 stdio 传输方式。
3.4 用 MCP Inspector 测试
MCP Inspector是官方提供的可视化调试工具,强烈推荐使用。
# 用 fastmcp dev 命令启动（会自动打开 Inspector） fastmcp dev server.py # 或用 npx 启动 Inspector npx @modelcontextprotocol/inspector python server.py浏览器自动打开http://127.0.0.1:6274,你会看到：
┌─────────────────────────────────────┐ │ MCP Inspector │ ├─────────────────────────────────────┤ │ Tools | Resources | Prompts │ ├─────────────────────────────────────┤ │ 📦 add │ │ "将两个数字相加" │ │ │ │ Inputs: │ │ a: [输入框] │ │ b: [输入框] │ │ │ │ [ Run Tool ] │ └─────────────────────────────────────┘输入a=3, b=5,点击 Run Tool,你会看到结果8。
🎉恭喜!你的第一个 MCP Server 已经能用了！
🔧 第四章：工具（Tools）深入详解
工具是 MCP Server 中最重要、使用最多的组件。让 AI"动手做事"全靠它。
4.1 基本语法
@mcp.tool def function_name(param1: type1, param2: type2 = default) -> return_type: """这是工具的描述（给 AI 看的）""" # 实现逻辑 return result4.2 支持的参数类型
FastMCP 基于Pydantic进行类型校验,几乎支持所有常见 Python 类型：
from typing import List, Dict, Optional, Literal, Union from pydantic import BaseModel # 基础类型 @mcp.tool def basic_types( name: str, age: int, height: float, is_active: bool ) -> str: return f"{name}, {age} 岁" # 复合类型 @mcp.tool def list_and_dict( tags: List[str], metadata: Dict[str, str] ) -> dict: return {"tags": tags, "metadata": metadata} # 可选参数（带默认值） @mcp.tool def optional_params( query: str, limit: int = 10, offset: Optional[int] = None ) -> list: return [f"result-{i}" for i in range(limit)] # 枚举类型（限定取值） @mcp.tool def enum_param( status: Literal["pending", "completed", "cancelled"] ) -> str: return f"状态：{status}" # Pydantic 模型（复杂结构） class User(BaseModel): name: str email: str age: int @mcp.tool def create_user(user: User) -> dict: return {"created": user.name, "email": user.email}4.3 异步工具
对于 I/O 密集型操作（API 调用、数据库查询）,建议用async：
import httpx @mcp.tool async def fetch_weather(city: str) -> dict: """获取指定城市的天气""" async with httpx.AsyncClient() as client: response