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.0FastMCP 经历了三个重要版本：版本时间说明FastMCP 1.02024已被并入官方 MCP Python SDK,即mcp.server.fastmcpFastMCP 2.02025独立维护的版本,加入认证、代理、中间件等高级功能FastMCP 3.02026 年 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（强烈推荐）或pip2.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 运行 Serverpython 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 + [e-mail]装饰器是关键!它自动做了三件事：工具名：使用函数名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