❤️ 如果你也关注 AI 的发展现状，且对 AI 应用开发感兴趣，我会每日分享大模型与 AI 领域的开源项目和应用，提供运行实例和实用教程，帮助你快速上手AI技术！
🥦 AI 在线答疑 -> 智能检索历史文章和开源项目 -> 丰富的 AI 工具库 -> 每日更新 -> 尽在微信公众号 -> 搜一搜：蚝油菜花 🥦
🚀 「FastAPI开发者福音！这个开源神器让API秒变AI工具，零配置自动转换」
大家好，我是蚝油菜花。你是否也经历过这些API对接的头痛时刻——
- 👉 想用AI调用内部API，却要手动编写大量适配代码
- 👉 接口文档和实际实现不同步，调试到怀疑人生
- 👉 每次新增端点都要重新配置AI工具，维护成本爆炸...
今天要介绍的 FastAPI-MCP ，正在重新定义API与AI的协作方式！这个开源利器只需3行代码：
✅ 零配置转换：自动发现所有FastAPI端点，保留Swagger文档和参数校验
✅ 动态热更新：新增接口无需重启，实时同步到AI工具库
✅ 双模部署：支持挂载到现有服务或独立部署，适应各种架构
已有团队用它1小时完成内部系统AI化改造，接下来带你解锁这套「API即AI工具」的黑科技！
FastAPI-MCP 是什么
FastAPI-MCP 是一个能将 FastAPI 应用端点自动转换为符合模型上下文协议(MCP)的开源工具。它通过解析FastAPI的OpenAPI文档实现零配置转换，完整保留接口的请求/响应模型和Swagger文档。
该工具支持直接集成到现有FastAPI应用中，也可作为独立服务部署。基于Python类型系统和AST语法树分析技术，能自动识别路由参数、权限声明等元数据，实现API与AI工具的无缝对接。
FastAPI-MCP 的主要功能
- 自动发现与转换：自动扫描FastAPI应用中的所有端点，转换为MCP工具格式，无需手动注册
- 文档完整性保留：完整继承Swagger文档描述和参数校验规则，确保AI调用准确性
- 灵活部署模式：支持挂载到原应用或独立部署，适配不同架构需求
- 智能端点筛选：通过operation_id或标签控制暴露的接口范围
- 动态热更新：运行时可刷新服务目录，自动包含新增端点
- 多协议支持：原生兼容SSE协议，通过mcp-proxy适配非SSE客户端
FastAPI-MCP 的技术原理
- OpenAPI规范解析：通过解析FastAPI自动生成的OpenAPI文档，提取接口元数据生成MCP工具定义
- 反射式元数据捕获：利用Python类型注解和Pydantic模型，自动获取参数结构和返回值类型
- AST语法树分析：静态分析路由装饰器代码，提取operation_id等关键信息
- 动态路由注册：运行时构建服务目录树，支持端点热更新
- 异步任务编排：基于Starlette事件循环实现高并发处理
如何运行 FastAPI-MCP
FastAPI-MCP 是一个零配置工具，用于将 FastAPI 的端点自动暴露为 Model Context Protocol (MCP) 工具。它支持直接集成、自动发现端点、保留模式和文档等功能。以下是详细的安装和使用教程。
安装
这里推荐使用uv，这是一个快速的 Python 包安装器：
uv add fastapi-mcp
你也可以使用 pip 进行安装：
pip install fastapi-mcp
基本用法
最简单的使用 FastAPI-MCP 的方法是直接将 MCP 服务器添加到你的 FastAPI 应用中：
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
# 可选参数
name="My API MCP",
description="My API description",
base_url="http://localhost:8000",
)
# 将 MCP 服务器直接挂载到 FastAPI 应用
mcp.mount()
就这样！你的自动生成的 MCP 服务器现在可以在 https://app.base.url/mcp 上访问。
关于
base_url的注意事项：虽然base_url是可选的，但强烈建议显式提供。base_url告诉 MCP 服务器在调用工具时将 API 请求发送到哪里。如果不提供，库会尝试自动确定 URL，这在内部和外部 URL 不同的部署环境中可能无法正常工作。
工具命名
FastAPI-MCP 使用 FastAPI 路由中的 operation_id 作为 MCP 工具的名称。如果你不指定 operation_id，FastAPI 会自动生成一个，但这些名称可能难以理解。
比较以下两个端点定义：
# 自动生成的 operation_id（类似于 "read_user_users__user_id__get"）
@app.get("/users/{user_id}")
async def read_user(user_id: int):
return {
"user_id": user_id}
# 显式的 operation_id（工具将被命名为 "get_user_info"）
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
return {
"user_id": user_id}
为了更清晰、更直观的工具名称，这里建议在 FastAPI 路由定义中添加显式的 operation_id 参数。
要了解更多，请阅读 FastAPI 的官方文档关于路径操作的高级配置。
高级用法
FastAPI-MCP 提供了多种方式来自定义和控制 MCP 服务器的创建和配置。以下是一些高级用法模式：
1. 自定义模式描述
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
mcp = FastApiMCP(
app,
name="My API MCP",
base_url="http://localhost:8000",
describe_all_responses=True, # 在工具描述中包含所有可能的响应模式
describe_full_response_schema=True # 在工具描述中包含完整的 JSON 模式
)
mcp.mount()
2. 自定义暴露的端点
你可以使用 OpenAPI 操作 ID 或标签来控制哪些 FastAPI 端点作为 MCP 工具暴露：
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
# 只包含特定操作
mcp = FastApiMCP(
app,
include_operations=["get_user", "create_user"]
)
# 排除特定操作
mcp = FastApiMCP(
app,
exclude_operations=["delete_user"]
)
# 只包含具有特定标签的操作
mcp = FastApiMCP(
app,
include_tags=["users", "public"]
)
# 排除具有特定标签的操作
mcp = FastApiMCP(
app,
exclude_tags=["admin", "internal"]
)
# 结合操作 ID 和标签（包含模式）
mcp = FastApiMCP(
app,
include_operations=["user_login"],
include_tags=["public"]
)
mcp.mount()
关于过滤的注意事项：
- 不能同时使用
include_operations和exclude_operations - 不能同时使用
include_tags和exclude_tags - 可以结合操作过滤和标签过滤（例如，使用
include_operations和include_tags） - 当结合过滤器时，将采用贪婪方法。匹配任一条件的端点将被包含
3. 单独部署
你不仅限于在同一 FastAPI 应用中提供 MCP 服务器。
你可以从一个 FastAPI 应用中创建 MCP 服务器，并将其挂载到另一个应用中：
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# 你的 API 应用
api_app = FastAPI()
# ... 在 api_app 上定义你的 API 端点 ...
# 一个单独的 MCP 服务器应用
mcp_app = FastAPI()
# 从 API 应用中创建 MCP 服务器
mcp = FastApiMCP(
api_app,
base_url="http://api-host:8001", # API 应用将运行的 URL
)
# 将 MCP 服务器挂载到单独的应用
mcp.mount(mcp_app)
# 现在你可以分别运行两个应用：
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000
4. 添加端点后刷新 MCP 服务器
如果你在创建 MCP 服务器后向 FastAPI 应用中添加了新的端点，你需要刷新服务器以包含这些新端点：
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
app = FastAPI()
# ... 定义初始端点 ...
# 创建 MCP 服务器
mcp = FastApiMCP(app)
mcp.mount()
# 在 MCP 服务器创建后添加新端点
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
return {
"message": "Hello, world!"}
# 刷新 MCP 服务器以包含新端点
mcp.setup_server()
通过 SSE 连接到 MCP 服务器
一旦你的 FastAPI 应用与 MCP 集成运行，你可以使用支持 SSE 的任何 MCP 客户端（例如 Cursor）连接到它：
- 运行你的应用。
- 在 Cursor -> 设置 -> MCP 中，使用你的 MCP 服务器端点 URL（例如
http://localhost:8000/mcp）作为 SSE。 - Cursor 会自动发现所有可用的工具和资源。
通过 mcp-proxy stdio 连接到 MCP 服务器
如果你的 MCP 客户端不支持 SSE，例如 Claude Desktop：
- 运行你的应用。
- 安装
mcp-proxy，例如：uv tool install mcp-proxy。 - 在 Claude Desktop MCP 配置文件 (
claude_desktop_config.json) 中添加：
在 Windows 上：
{
"mcpServers": {
"my-api-mcp-proxy": {
"command": "mcp-proxy",
"args": ["http://127.0.0.1:8000/mcp"]
}
}
}
在 MacOS 上：
{
"mcpServers": {
"my-api-mcp-proxy": {
"command": "/Full/Path/To/Your/Executable/mcp-proxy",
"args": ["http://127.0.0.1:8000/mcp"]
}
}
}
通过在终端中运行 which mcp-proxy 找到 mcp-proxy 的路径，Claude Desktop 会自动发现所有可用的工具和资源。
资源
❤️ 如果你也关注 AI 的发展现状，且对 AI 应用开发感兴趣，我会每日分享大模型与 AI 领域的开源项目和应用，提供运行实例和实用教程，帮助你快速上手AI技术！
🥦 AI 在线答疑 -> 智能检索历史文章和开源项目 -> 丰富的 AI 工具库 -> 每日更新 -> 尽在微信公众号 -> 搜一搜：蚝油菜花 🥦
