Python FastMCP中文文档
FastMCP v2 🚀
构建 MCP 服务器和客户端的快速、Pythonic 方式。
FastMCP 2.0 和官方 MCP SDK
觉得
FastMCP这个名字眼熟吗？您可能见过贡献给官方 MCP Python SDK 的版本，该版本基于 FastMCP 1.0。欢迎来到 FastMCP 2.0！ 这是积极开发的继任者，它在 1.0 的基础上进行了显著扩展，引入了强大的客户端功能、服务器代理和组合、OpenAPI/FastAPI 集成以及更多高级特性。
FastMCP 2.0 是构建现代化、强大 MCP 应用程序的推荐路径。准备好升级或开始使用了吗？请遵循安装说明，其中包含从官方 MCP SDK 升级的具体步骤。
模型上下文协议 (MCP) 是一种全新的标准化方式，用于向您的 LLM 提供上下文和工具，而 FastMCP 使构建 MCP 服务器和客户端变得简单直观。使用简洁的 Pythonic 代码创建工具、暴露资源、定义提示并连接组件。
# server.py
from fastmcp import FastMCP
mcp = FastMCP("演示 🚀")
@mcp.tool()
def add(a: int, b: int) -> int:
"""两个数字相加"""
return a + b
if __name__ == "__main__":
mcp.run()
在本地运行服务器：
fastmcp run server.py
📚 文档
FastMCP 的完整文档可在 gofastmcp.com 获取，包括详细指南、API 参考和高级模式。此 readme 文件仅提供高级概述。
文档也以 llms.txt 格式 提供，这是一种 LLM 可以轻松使用的简单 Markdown 标准。
有两种方式可以访问 LLM 友好的文档：
llms.txt本质上是一个站点地图，列出了文档中的所有页面。llms-full.txt包含完整的文档。请注意，这可能会超出您 LLM 的上下文窗口。
目录
什么是 MCP？
模型上下文协议 (MCP) 允许您构建服务器，以安全、标准化的方式向 LLM 应用程序暴露数据和功能。可以将其视为 Web API，但专为 LLM 交互设计。MCP 服务器可以：
- 通过资源暴露数据（类似于
GET请求；将信息加载到上下文中） - 通过工具提供功能（类似于
POST/PUT请求；执行操作） - 通过提示定义交互模式（可重用模板）
- 以及更多！
FastMCP 为构建和与这些服务器交互提供了高级的、Pythonic 的接口。
为什么选择 FastMCP？
MCP 协议功能强大，但实现它涉及大量样板代码——服务器设置、协议处理程序、内容类型、错误管理。FastMCP 处理所有复杂的协议细节和服务器管理，因此您可以专注于构建出色的工具。它被设计为高级且 Pythonic 的；在大多数情况下，您只需要装饰一个函数即可。
虽然 FastMCP 1.0 的核心服务器概念奠定了基础并被贡献给了官方 MCP SDK，但 FastMCP 2.0（本项目）是积极开发的继任者，增加了显著的增强功能和全新的能力，例如强大的客户端库、服务器代理、组合模式、OpenAPI/FastAPI 集成等等。
FastMCP 旨在：
🚀 快速： 高级接口意味着更少的代码和更快的开发速度
🍀 简单： 以最少的样板代码构建 MCP 服务器
🐍 Pythonic： 对 Python 开发者而言感觉自然
🔍 完整： FastMCP 旨在为服务器和客户端提供核心 MCP 规范的完整实现
安装
我们建议使用 uv 安装 FastMCP：
uv pip install fastmcp
有关完整的安装说明，包括验证、从官方 MCPSDK 升级和开发者设置，请参阅安装指南。
核心概念
这些是使用 FastMCP 创建 MCP 服务器和客户端的构建块。
The FastMCP 服务器
代表您的 MCP 应用程序的中心对象。它包含您的工具、资源和提示，管理连接，并且可以通过诸如身份验证提供者之类的设置进行配置。
from fastmcp import FastMCP
# 创建一个服务器实例
mcp = FastMCP(name="我的助手服务器")
在FastMCP 服务器文档中了解更多。
工具
工具允许 LLM 通过执行您的 Python 函数（同步或异步）来执行操作。非常适合计算、API 调用或副作用（如 POST/PUT）。FastMCP 根据类型提示和文档字符串处理模式生成。工具可以返回各种类型，包括文本、JSON 可序列化对象，甚至使用 fastmcp.Image 助手的图像。
@mcp.tool()
def multiply(a: float, b: float) -> float:
"""将两个数字相乘。"""
return a * b
在工具文档中了解更多。
资源与模板
资源暴露只读数据源（如 GET 请求）。使用 @mcp.resource("your://uri")。在 URI 中使用 {占位符} 来创建接受参数的动态模板，允许客户端请求特定的数据子集。
# 静态资源
@mcp.resource("config://version")
def get_version():
return "2.0.1"
# 动态资源模板
@mcp.resource("users://{user_id}/profile")
def get_profile(user_id: int):
# 获取 user_id 的配置文件...
return {"name": f"用户 {user_id}", "status": "active"}
在资源与模板文档中了解更多。
提示
提示定义可重用的消息模板以指导 LLM 交互。使用 @mcp.prompt() 装饰函数。返回字符串或 Message 对象。
@mcp.prompt()
def summarize_request(text: str) -> str:
"""生成一个请求摘要的提示。"""
return f"请总结以下文本：\n\n{text}"
在提示文档中了解更多。
上下文
通过添加 ctx: Context 参数，在您的工具、资源或提示中访问 MCP 会话功能。上下文提供以下方法：
- 日志记录： 使用
ctx.info()、ctx.error()等向 MCP 客户端记录消息。 - LLM 采样： 使用
ctx.sample()请求客户端 LLM 的补全。 - HTTP 请求： 使用
ctx.http_request()向其他服务器发出 HTTP 请求。 - 资源访问： 使用
ctx.read_resource()访问服务器上的资源。 - 进度报告： 使用
ctx.report_progress()向客户端报告进度。 - 以及更多...
要访问上下文，请向任何 mcp 装饰的函数添加一个注解为 Context 的参数。当函数被调用时，FastMCP 将自动注入正确的上下文对象。
from fastmcp import FastMCP, Context
mcp = FastMCP("我的 MCP 服务器")
@mcp.tool()
async def process_data(uri: str, ctx: Context):
# 向客户端记录一条消息
await ctx.info(f"正在处理 {uri}...")
# 从服务器读取资源
data = await ctx.read_resource(uri)
# 请求客户端 LLM 总结数据
summary = await ctx.sample(f"总结：{data.content[:500]}")
# 返回摘要
return summary.text
在上下文文档中了解更多。
MCP 客户端
使用 fastmcp.Client 以编程方式与任何 MCP 服务器交互。它支持各种传输方式（Stdio、SSE、内存中），并且通常会自动检测正确的传输方式。如果您提供适当的处理程序，客户端还可以处理高级模式，例如服务器发起的 LLM 采样请求。
至关重要的是，客户端允许通过 FastMCPTransport 直接连接到 FastMCP 服务器实例，从而实现服务器的有效内存中测试，无需在测试期间进行进程管理或网络调用。
from fastmcp import Client
async def main():
# 通过 stdio 连接到本地脚本
async with Client("my_server.py") as client:
tools = await client.list_tools()
print(f"可用工具：{tools}")
result = await client.call_tool("add", {"a": 5, "b": 3})
print(f"结果：{result.text}")
# 通过 SSE 连接
async with Client("http://localhost:8000/sse") as client:
# ... 使用客户端
pass
要使用客户端测试服务器，请使用以下模式：
from fastmcp import FastMCP, Client
mcp = FastMCP("我的 MCP 服务器")
async def main():
# 通过内存中传输连接
async with Client(mcp) as client:
# ... 使用客户端
高级特性
FastMCP 引入了构建和部署 MCP 应用程序的强大方法。
代理服务器
使用 FastMCP.from_client() 创建一个 FastMCP 服务器，作为另一个本地或远程 MCP 服务器的中介。这对于桥接传输（例如，远程 SSE 到本地 Stdio）或向您无法控制的服务器添加逻辑层特别有用。
在代理文档中了解更多。
组合 MCP 服务器
通过使用 mcp.mount()（实时链接）或 mcp.import_server()（静态副本）将多个 FastMCP 实例挂载到父服务器上，构建模块化应用程序。
在组合文档中了解更多。
OpenAPI 与 FastAPI 生成
从现有的 OpenAPI 规范（FastMCP.from_openapi()）或 FastAPI 应用程序（FastMCP.from_fastapi()）自动生成 FastMCP 服务器，立即将您的 Web API 引入 MCP 生态系统。
了解更多：OpenAPI 集成 | FastAPI 集成。
运行您的服务器
运行 FastMCP 服务器的主要方法是在服务器实例上调用 run() 方法：
# server.py
from fastmcp import FastMCP
mcp = FastMCP("演示 🚀")
@mcp.tool()
def hello(name: str) -> str:
return f"你好，{name}！"
if __name__ == "__main__":
mcp.run() # 默认：使用 STDIO 传输
FastMCP 支持三种传输协议：
STDIO (默认)：最适合本地工具和命令行脚本。
mcp.run(transport="stdio") # 默认，因此 transport 参数是可选的
可流式 HTTP (Streamable HTTP)：推荐用于 Web 部署。
mcp.run(transport="streamable-http", host="127.0.0.1", port=8000, path="/mcp")
SSE：用于与现有 SSE 客户端兼容。
mcp.run(transport="sse", host="127.0.0.1", port=8000)
有关更多详细信息，请参阅运行服务器文档。
浙公网安备 33010602011771号