❤️ 如果你也关注 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 应用端点自动转换为符合模型上下文协议(MCP)的开源工具。它通过解析FastAPI的OpenAPI文档实现零配置转换，完整保留接口的请求/响应模型和Swagger文档。

该工具支持直接集成到现有FastAPI应用中，也可作为独立服务部署。基于Python类型系统和AST语法树分析技术，能自动识别路由参数、权限声明等元数据，实现API与AI工具的无缝对接。

FastAPI-MCP 的主要功能

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：https://docs.astral.sh/uv/

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 路径操作的高级配置：https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/

高级用法

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-proxy stdio：https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file#1-stdio-to-sse

如果你的 MCP 客户端不支持 SSE，例如 Claude Desktop：

mcp-proxy：https://github.com/sparfenyuk/mcp-proxy?tab=readme-ov-file#installing-via-pypi

运行你的应用。
安装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 会自动发现所有可用的工具和资源。

资源

GitHub 仓库：https://github.com/tadata-org/fastapi_mcp