使用说明
FastMCP v2🚀
构建MCP服务器和客户端的快速Python方法。
制作☕️ by 完美
[！注意]
FastMCP 2.0：标准框架
FastMCP是Python MCP开发的先驱，FastMCP 1.0被整合到 官方MCP SDK 2024年。
这是FastMCP 2.0 --积极维护、生产就绪的框架，远远超出了基本协议的实现。虽然SDK提供了核心功能，但FastMCP 2.0提供了生产所需的一切：高级MCP模式（服务器组合、代理、OpenAPI/FastAPI生成、工具转换）、企业身份验证（谷歌、GitHub、WorkOS、Azure、Auth0等）、部署工具、测试实用程序和全面的客户端库。
对于生产MCP应用程序，请安装FastMCP：
pip install fastmcp
FastMCP是构建MCP应用程序的标准框架，提供从创意到生产的最快途径。
这个 模型上下文协议（MCP） 是一种为LLM提供上下文和工具的标准化方法。FastMCP使构建生产就绪的MCP服务器变得简单，内置了企业身份验证、部署工具和完整的生态系统。
# server.py
from fastmcp import FastMCP
mcp = FastMCP("Demo 🚀")
@mcp.tool
def add(a: int, b: int) -> int:
"""Add two numbers"""
return a + b
if __name__ == "__main__":
mcp.run()
在本地运行服务器：
fastmcp run server.py
📚 文档
FastMCP的完整文档可在 gofastmcp.com，包括详细指南、API参考资料和高级模式。本自述文件仅提供了一个高层次的概述。
文档也可在 llms.txt格式，这是LLM可以轻松使用的简单降价标准。
有两种方法可以访问LLM友好文档：
llms.txt本质上是一个站点地图，列出了文档中的所有页面。llms-full.txt包含整个文档。请注意，这可能会超出LLM的上下文窗口。
目录
什么是MCP？
这个 模型上下文协议（MCP） 允许您构建以安全、标准化的方式向LLM应用程序公开数据和功能的服务器。它通常被描述为“AI的USB-C端口”，提供了一种将LLM连接到它们可以使用的资源的统一方式。将其视为API可能更容易，但它是专门为LLM交互而设计的。MCP服务器可以：
- 通过以下方式公开数据 资源 （将这些类似于GET端点；它们用于将信息加载到LLM的上下文中）
- 通过以下方式提供功能 工具 （有点像POST端点；它们用于执行代码或产生副作用）
- 通过以下方式定义交互模式 提示 （LLM交互的可重用模板）
- 还有更多！
FastMCP提供了一个高级的Python接口，用于构建、管理和与这些服务器交互。
为什么选择FastMCP？
FastMCP处理所有复杂的协议细节，因此您可以专注于构建。在大多数情况下，你只需要装饰一个Python函数——剩下的由FastMCP处理。
🚀 快速： 高级接口意味着更少的代码和更快的开发
🍀 简单： 使用最少的样板构建MCP服务器
🐍 Python： 对Python开发人员来说感觉很自然
🔍 完成： 一切用于生产——企业身份验证（谷歌、GitHub、Azure、Auth0、WorkOS）、部署工具、测试框架、客户端库等
FastMCP提供了从创意到生产的最短路径。在本地部署到云端 FastMCP云，或者连接到您自己的基础设施。
安装
我们建议安装FastMCP 紫外线:
uv pip install fastmcp
有关完整的安装说明，包括验证、从官方MCPSDK升级和开发人员设置，请参阅 安装指南.
核心概念
这些是使用FastMCP创建MCP服务器和客户端的构建块。
这个 FastMCP 服务器
代表MCP应用程序的中心对象。它保存您的工具、资源和提示，管理连接，并可以配置身份验证等设置。
from fastmcp import FastMCP
# Create a server instance
mcp = FastMCP(name="MyAssistantServer")
在 FastMCP服务器文档.
工具
工具允许LLM通过执行Python函数（同步或异步）来执行操作。适用于计算、API调用或副作用（如 POST/PUT).FastMCP处理从类型提示和文档字符串生成模式。工具可以返回各种类型，包括文本、JSON可序列化对象，甚至是FastMCP媒体助手类辅助的图像或音频。
@mcp.tool
def multiply(a: float, b: float) -> float:
"""Multiplies two numbers."""
return a * b
在 工具文档.
资源和模板
资源公开只读数据源（如 GET 请求：使用 @mcp.resource("your://uri").使用 {placeholders} 在URI中创建接受参数的动态模板，允许客户端请求特定的数据子集。
# Static resource
@mcp.resource("config://version")
def get_version():
return "2.0.1"
# Dynamic resource template
@mcp.resource("users://{user_id}/profile")
def get_profile(user_id: int):
# Fetch profile for user_id...
return {"name": f"User {user_id}", "status": "active"}
在 资源和模板文档.
提示
提示定义可重用的消息模板来指导LLM交互。用以下方式装饰功能 @mcp.prompt.返回字符串或 Message 物体。
@mcp.prompt
def summarize_request(text: str) -> str:
"""Generate a prompt asking for a summary."""
return f"Please summarize the following text:\n\n{text}"
在 提示文档.
上下文
通过添加 ctx: Context 参数。上下文提供了以下方法：
- 登录中： 使用以下命令将消息记录到MCP客户端
ctx.info(),ctx.error()等等。 - LLM取样： 使用
ctx.sample()向客户的LLM请求完成。 - HTTP请求： 使用
ctx.http_request()向其他服务器发出HTTP请求。 - 资源访问： 使用
ctx.read_resource()访问服务器上的资源 - 进度报告： 使用
ctx.report_progress()向客户报告进度。 - 以及更多。..
要访问上下文，请添加一个注释为的参数 Context 任何mcp装饰功能。当函数被调用时，FastMCP将自动注入正确的上下文对象。
from fastmcp import FastMCP, Context
mcp = FastMCP("My MCP Server")
@mcp.tool
async def process_data(uri: str, ctx: Context):
# Log a message to the client
await ctx.info(f"Processing {uri}...")
# Read a resource from the server
data = await ctx.read_resource(uri)
# Ask client LLM to summarize the data
summary = await ctx.sample(f"Summarize: {data.content[:500]}")
# Return the summary
return summary.text
在 上下文文档.
MCP客户端
互动 任何 MCP服务器以编程方式使用 fastmcp.Client它支持多种传输方式（Stdio、SSE、In-Memory），并经常自动检测正确的传输方式。客户端还可以处理服务器启动等高级模式 LLM采样请求 如果你提供了一个合适的处理程序。
至关重要的是，客户端允许高效 内存测试 通过直接连接到 FastMCP 服务器实例通过 FastMCPTransport，消除了测试期间对流程管理或网络调用的需要。
from fastmcp import Client
async def main():
# Connect via stdio to a local script
async with Client("my_server.py") as client:
tools = await client.list_tools()
print(f"Available tools: {tools}")
result = await client.call_tool("add", {"a": 5, "b": 3})
print(f"Result: {result.content[0].text}")
# Connect via SSE
async with Client("http://localhost:8000/sse") as client:
# ... use the client
pass
要使用客户端测试服务器，请使用以下模式：
from fastmcp import FastMCP, Client
mcp = FastMCP("My MCP Server")
async def main():
# Connect via in-memory transport
async with Client(mcp) as client:
# ... use the client
FastMCP还支持使用标准MCP配置格式通过单个统一客户端连接到多个服务器：
from fastmcp import Client
# Standard MCP configuration with multiple servers
config = {
"mcpServers": {
"weather": {"url": "https://weather-api.example.com/mcp"},
"assistant": {"command": "python", "args": ["./assistant_server.py"]}
}
}
# Create a client that connects to all servers
client = Client(config)
async def main():
async with client:
# Access tools and resources with server prefixes
forecast = await client.call_tool("weather_get_forecast", {"city": "London"})
answer = await client.call_tool("assistant_answer_question", {"query": "What is MCP?"})
认证
企业身份验证，零配置
FastMCP提供全面的身份验证支持，使其有别于基本的MCP实现。保护您的服务器，并使用大公司使用的相同企业级提供商对您的客户端进行身份验证。
内置OAuth提供程序：
- 谷歌
- GitHub
- 微软 Azure
- 身份验证0
- WorkOS
- 降级
- JWT/定制
- API密钥
保护服务器只需要两行：
from fastmcp.server.auth import GoogleProvider
auth = GoogleProvider(client_id="...", client_secret="...", base_url="https://myserver.com")
mcp = FastMCP("Protected Server", auth=auth)
连接到受保护的服务器更简单：
async with Client("https://protected-server.com/mcp", auth="oauth") as client:
# Automatic browser-based OAuth flow
result = await client.call_tool("protected_tool")
为什么FastMCP认证很重要：
- 生产就绪： 持久存储、令牌刷新、全面的错误处理
- 零配置OAuth： 请通过
auth="oauth"用于自动设置 - 企业集成： WorkOS SSO、Azure Active Directory、Auth0租户
- 开发人员经验： 浏览器自动启动，本地回调服务器，环境变量支持
- 高级架构： 完整的OIDC支持、动态客户端注册（DCR）和独特的OAuth代理模式，可与任何提供商进行DCR
这种全面的身份验证是FastMCP 2.0独有的。
部署
从开发到生产
FastMCP支持从本地开发到全球规模的所有部署场景：
发展： 使用单个命令在本地运行
fastmcp run server.py
生产： 部署到 FastMCP云 --刚刚工作的远程MCP
- 即时HTTPS端点
- 内置身份验证
- 零配置
- 个人服务器免费
自托管： 为您自己的基础设施使用HTTP或SSE传输
mcp.run(transport="http", host="0.0.0.0", port=8000)
在 部署文档.
高级功能
FastMCP引入了构建和组合MCP应用程序的强大方法。
代理服务器
使用以下命令创建充当另一个本地或远程MCP服务器中介的FastMCP服务器 FastMCP.as_proxy()。这对于桥接传输（例如，远程SSE到本地Stdio）或向您不控制的服务器添加一层逻辑特别有用。
在 代理文档.
组成MCP服务器
通过安装多个模块构建模块化应用程序 FastMCP 使用以下命令将实例添加到父服务器上 mcp.mount() （实时链接）或 mcp.import_server() （静态副本）。
在 成分文件.
OpenAPI和FastAPI生成
根据现有的OpenAPI规范自动生成FastMCP服务器(FastMCP.from_openapi())或FastAPI应用程序(FastMCP.from_fastapi())，立即将您的web API引入MCP生态系统。
运行服务器
运行FastMCP服务器的主要方法是调用 run() 服务器实例上的方法：
# server.py
from fastmcp import FastMCP
mcp = FastMCP("Demo 🚀")
@mcp.tool
def hello(name: str) -> str:
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run() # Default: uses STDIO transport
FastMCP支持三种传输协议：
STDIO（默认）：最适合本地工具和命令行脚本。
mcp.run(transport="stdio") # Default, so transport argument is optional
流式HTTP：建议用于web部署。
mcp.run(transport="http", host="127.0.0.1", port=8000, path="/mcp")
上海证券交易所：与现有SSE客户端兼容。
mcp.run(transport="sse", host="127.0.0.1", port=8000)
看 运行服务器文档 了解更多详情。
贡献
贡献是开源的核心！我们欢迎改进和功能。
先决条件
- Python 3.10+
- 紫外线 （建议用于环境管理）
设置
-
克隆存储库：
git clone https://github.com/jlowin/fastmcp.git cd fastmcp -
创建并同步环境：
uv sync这将安装所有依赖项，包括开发工具。
-
激活虚拟环境（例如。，
source .venv/bin/activate或通过IDE）。
单元测试
FastMCP有一个全面的单元测试套件。所有PR必须酌情引入或更新测试，并通过整套测试。
使用pytest运行测试：
pytest
或者，如果您想了解代码覆盖率的概述
uv run pytest --cov=src --cov=examples --cov-report=html
静态检查
FastMCP使用 pre-commit 用于代码格式化、linting和类型检查。所有PR都必须通过这些检查（它们在CI中自动运行）。
在本地安装挂钩：
uv run pre-commit install
钩子现在将自动运行 git commit。您也可以随时手动运行它们：
pre-commit run --all-files
# or via uv
uv run pre-commit run --all-files
拉取请求
- 在GitHub上分叉存储库。
- 从以下位置创建要素分支
main. - 进行更改，包括测试和文档更新。
- 确保测试和预提交挂钩通过。
- 提交你的更改并推动你的叉子。
- 对打开pull请求
main的分支jlowin/fastmcp.
请在开始重要工作之前，就问题或建议展开讨论！
