一、背景与概述

FastAPI-MCP 是一个零配置工具，用于自动将 FastAPI 端点公开为模型上下文协议（MCP）工具，并内置认证机制，帮助开发者快速将已有的 RESTful API 集成到 LLM 工具链中，无需额外编写转换或桥接代码。

二、核心特性

• 直接集成：将 MCP 服务器直接挂载到您的 FastAPI 应用中，一行代码即可完成集成。
• 零配置：自动发现所有 FastAPI 路由，并转换为 MCP 工具，开箱即用。
• 保留模式与文档：完整保留请求模型和响应模型的 JSON Schema，以及 Swagger 文档中对各端点的描述。
• 灵活部署：支持在同一应用中挂载 MCP 服务，也可分离部署；默认通过 ASGI 直连 FastAPI 应用，大幅提高调用效率。

三、安装与快速入门

推荐使用超快的包管理工具 uv 进行安装：

uv add fastapi-mcp

或通过 pip 安装：

pip install fastapi-mcp
```citeturn2view0

在您的 FastAPI 应用中，仅需三行代码即可启动 MCP 服务：
```python
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()

此时，所有 API 路由将自动以 MCP 工具形式暴露，默认访问路径为 /mcp。

四、工具命名最佳实践

FastAPI-MCP 使用路由的 operation_id 作为 MCP 工具名称。若未显式指定，FastAPI 会生成类似 read_user_users__user_id__get 的名称，阅读体验较差。
建议在路由定义中添加清晰的 operation_id，例如：

@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

五、高级用法

5.1.自定义描述

通过初始化参数可灵活控制工具描述内容：

mcp = FastApiMCP(
    app,
    name="我的 API MCP",
    describe_all_responses=True,         # 包含所有响应模式
    describe_full_response_schema=True   # 包含完整 JSON Schema
)
mcp.mount()

这样，MCP 工具中将展示更丰富的模式信息。

5.2.端点过滤

可使用 include_operations、exclude_operations、include_tags 和 exclude_tags 等参数，精准控制哪些端点被暴露为 MCP 工具。

5.3.分离部署

您可以在一个应用中定义 API，在另一个应用中运行 MCP 服务，实现独立部署：

# api_app 中定义业务路由…
api_app = FastAPI()

# mcp_app 用于暴露 MCP 服务
mcp_app = FastAPI()
mcp = FastApiMCP(api_app)
mcp.mount(mcp_app)

分别启动两个服务即可：

uvicorn main:api_app --port 8001
uvicorn main:mcp_app --port 8000

5.4.动态刷新

在 MCP 服务创建后新增路由时，调用：

mcp.setup_server()

即可重新扫描并加载最新端点。

5.5.自定义传输

默认使用 ASGI 直连，如需指定 HTTP 客户端，可传入自定义的 httpx.AsyncClient：

import httpx

custom_client = httpx.AsyncClient(base_url="https://api.example.com", timeout=30.0)
mcp = FastApiMCP(app, http_client=custom_client)
mcp.mount()

六、实践示例

• SSE 连接：在支持 SSE 的客户端（如 Cursor）中，配置 MCP 服务 URL 后即可自动发现并调用所有工具。
• mcp-proxy 隧道：对于不支持 SSE 的客户端（如 Claude Desktop），安装 mcp-proxy，在配置文件中指定命令和参数，即可通过标准输入/输出与 MCP 服务通信。

七、要求与许可

• 运行环境：Python 3.10+（推荐 3.12）
• 安装工具：uv（或 pip）
• 开源协议：MIT License © 2024 Tadata Inc.

八、总结

FastAPI-MCP 以“零配置”、“FastAPI 原生扩展”及“灵活部署”为核心优势，极大简化了将已有 API 转换为 MCP 工具的工作，对于构建高效、安全的 LLM 工具链具有重要价值。欢迎试用并反馈体验！