FastAPI-MCP：将 FastAPI 接口变成 AI 工具的桥梁

场景切入：当你的内部 API 被 Claude「看见」

想象一下：你在公司内部部署了一套订单管理系统，用 FastAPI 写了二十多个接口——查询订单、审核退款、生成报表——这些接口原本只有前端工程师通过 HTTP 调用。

但现在，你希望 AI 助手（如 Claude、Cursor、Windsurf）也能调用这些接口，帮你自动完成数据整理、报表生成等任务。问题是：AI 怎么知道这些接口是什么？它不认识你写的 Python 函数。

FastAPI-MCP 就是来解决这个问题的：它像一个「翻译官」，把你的 FastAPI 接口自动转换成 AI 能理解的 MCP 工具（Tools），让 Claude 等 AI 助手直接调用你的内部接口，就像调用内置功能一样自然。

背景：MCP 协议与 FastAPI 的相遇

MCP（Model Context Protocol，模型上下文协议）由 Anthropic 提出，是一种让 AI 模型与外部工具交互的标准化协议。打个比方：如果把 AI 比作一个只会做PPT的实习生，MCP 就是给他配备的「工位工具箱」——有了工具箱，他才能真正帮你完成报告、数据分析、操作系统的任务。

FastAPI 是目前最流行的 Python Web 框架之一，以高性能、自动文档生成（Swagger UI）和类型安全著称。很多公司内部工具、API 服务都用 FastAPI 构建。Tadata 团队敏锐地发现了这个需求：为什么不让 FastAPI 的接口直接变成 MCP 工具呢？于是 FastAPI-MCP 应运而生。

这个项目由 Tadata 团队开发和维护，已获得 11,800+ GitHub Stars，是当前 MCP Server 生态中最受欢迎的 FastAPI 集成工具之一。

核心功能：三行代码，让 AI 调用你的接口

零配置集成

使用 FastAPI-MCP 只需要两行代码：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()  # 就这样！

Mount 之后，你的 FastAPI 应用自动在 /mcp 路径下暴露 MCP 服务，Claude 等支持 MCP 的客户端可以直接连接。

自动端点发现与转换

FastAPI-MCP 通过读取 FastAPI 的 OpenAPI Schema，自动将所有路由端点转换为 MCP 工具。转换过程中会保留：

• 请求参数模型（Pydantic models）：AI 调用时会自动校验参数类型
• 响应数据模型：返回结果会自动序列化
• 文档字符串：每个端点的 docstring 会变成工具的 description

也就是说，你写 FastAPI 时就已经在给 AI 写工具文档了，一举两得。

灵活的部署模式

FastAPI-MCP 支持两种部署方式：

1. 嵌入式：MCP 服务器挂载到同一个 FastAPI 应用中（mcp.mount()），最简单
2. 独立部署：MCP 服务器单独运行，适合微服务架构

认证与权限控制

这是 FastAPI-MCP 的亮点功能。团队在接入 AI 工具时最担心的问题之一是：AI 能否调用内部接口的权限控制怎么办？

FastAPI-MCP 支持以下认证方式：

• Bearer Token：在 MCP 连接时传递 Authorization header
• OAuth 2.0：标准 OAuth 流程，支持第三方 AI 客户端
• 自定义认证函数：可以接入公司现有的 SSO/Cookie 认证体系

这样，即使你的内部接口需要登录才能访问，FastAPI-MCP 也能帮你把认证信息正确传递给后端。

工具过滤与命名

不想把所有端点都暴露给 AI？可以通过 include_operations 或 exclude_operations 参数精确控制哪些端点变成 MCP 工具。

工具名称默认使用 FastAPI 路由的 operation_id，也可以通过装饰器自定义，让 AI 看到的工具名更语义化。

技术架构：薄而专注的适配层

FastAPI-MCP 的代码结构非常清晰，是一个典型的「适配层」设计：

fastapi_mcp/
├── __init__.py      # 导出 FastApiMCP 核心类
├── server.py        # FastApiMCP 主类，编排 MCP Server
├── auth.py          # 认证配置（OAuth、Token、自定义）
├── types.py         # 类型定义（AuthConfig、OAuthMetadata）
├── openapi/
│   └── convert.py   # 核心：OpenAPI Schema → MCP Tools 转换
├── transport/
│   ├── sse.py        # SSE 传输（服务端推送事件）
│   └── http.py      # HTTP 长轮询传输
└── utils.py         # Schema 清理、示例生成等工具函数

核心技术栈：

• FastAPI：Web 框架，提供 OpenAPI Schema
• mcp (Model Context Protocol)：Anthropic 的 MCP Python SDK
• Pydantic v2：数据验证与序列化
• httpx：异步 HTTP 客户端

转换流程简述：FastAPI app → get_openapi() → OpenAPI Schema → convert_openapi_to_mcp_tools() → List[mcp.types.Tool]。这个流程保证了所有 FastAPI 原生特性（依赖注入、中间件、响应模型）都能正确传递到 MCP 层。

上手难度：Python 开发者零门槛

适合人群：有 FastAPI 基础的 Python 开发者

前提知识：了解 FastAPI 路由定义、MCP 概念（可选，文档中有介绍）

安装方式：uv add fastapi-mcp 或 pip install fastapi-mcp

Python 版本：>= 3.10

由于是纯 Python 库且依赖成熟，不需要 GPU、不需要 Docker，直接 pip 安装即可。文档中有完整的中文 README 和 Getting Started 指南。

局限与挑战

1. 依赖上游 MCP 生态：FastAPI-MCP 的能力上限取决于 Claude/Cursor 等客户端对 MCP 协议的支持程度。如果某个 AI 工具不支持 MCP，这个库就无法发挥作用。

2. 嵌套参数处理：对于非常复杂的嵌套 Pydantic 模型，转换为 MCP 工具参数时可能出现信息损失，需要仔细测试。

3. 大规模端点暴露：当 FastAPI 应用有几百个端点时，全部暴露给 MCP 可能导致工具列表过长，影响 AI 的选择和调用效率。建议配合 include_operations 做精细化控制。

4. 当前版本为 Alpha：PyPI 分类显示 Development Status :: 3 - Alpha，API 可能存在 breaking changes，生产环境使用需注意版本锁定。

行业意义：填补 AI 工具与内部系统的最后一公里

2024-2025 年，AI Coding 工具（Cursor、Windsurf、GitHub Copilot）迅速普及，但它们普遍面临同一个问题：无法调用企业的内部工具和 API。员工想让 AI 帮忙查数据、调接口，但 AI 根本没有权限访问这些系统。

FastAPI-MCP 代表了一种解决路径：不用改造 AI 工具本身，也不用给每个接口重写 MCP 包装层，只需在 FastAPI 这侧加一个薄薄的适配器，就能让所有内部 API 被 AI 工具发现和使用。这是典型的「最小改动、最大收益」设计思路。

从 GitHub Stars 增长曲线看（2025 年中上线，当前 11,800+ Stars），这个赛道正在快速升温。随着 MCP 协议被更多厂商采纳，类似 FastAPI-MCP 的适配层工具将成为企业 AI 化的标配组件。