/ 目录 / 演练场 / FastAPI MCP
← 全部服务器 ↗ GitHub
● 社区 tadata-org ⚡ 即开即用

FastAPI MCP

作者 tadata-org · tadata-org/fastapi_mcp

一行代码挂载，将每个 FastAPI 路由转变为 MCP 工具——模式来自你的 Pydantic 模型，认证来自你的中间件。

fastapi-mcp 包装现有的 FastAPI 应用，将其路由暴露为 MCP 工具。工具模式从你的 Pydantic 请求/响应模型自动生成。现有的认证中间件无需改动就能继续运行。从'我有一个 Python API'到'智能体可以调用它'的最快方式。

▶ 观看演示 📦 安装 💡 使用场景

为什么要用

核心特性

实时演示

实际使用效果

fastapi-mcp.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标，然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "fastapi-mcp",
      "command": "uvx",
      "args": [
        "fastapi-mcp"
      ]
    }
  ]
}

Continue 使用服务器对象数组，而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "fastapi-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "fastapi-mcp"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add fastapi-mcp -- uvx fastapi-mcp

一行命令搞定。用 claude mcp list 验证，claude mcp remove 卸载。

使用场景

实战用法： FastAPI MCP

无需重构地将现有 FastAPI 应用暴露为 MCP

👤 拥有运行中 FastAPI 服务的后端开发者 ⏱ ~30 min intermediate

何时使用： 你已经部署了 FastAPI API。你想让智能体使用它。你不想维护并行的代码库。

前置条件
  • 能正常运行的 FastAPI 应用，其请求/响应使用 Pydantic 模型 — 如果你的路由返回 dict，先重构为 Pydantic BaseModel——否则工具模式会是 object
步骤
  1. 安装和挂载
    将 fastapi-mcp 添加到我的项目。在 main.py 中，app = FastAPI() 之后，添加 FastApiMCP(app).mount()。显示差异。✓ 已复制
    → 差异很小；服务器仍能运行
  2. 验证工具出现
    运行服务器。用 npx -y mcp-remote http://localhost:8000/mcp 连接。列出工具——我的所有 GET/POST 路由都显示了吗？✓ 已复制
    → 工具已列出，名称与路由 operation_id 匹配
  3. 过滤暴露内容
    我不想暴露 /admin/* 路由。用 include_operations 重新配置或通过标签排除。✓ 已复制
    → 管理路由不再显示在工具列表中

结果： 你的现有 API 现在是 MCP 可寻址的，模式和逻辑无任何重复。

注意事项
  • 每个路由都会变成工具——包括你没打算暴露的内部路由 — 在上线前显式设置 include_tags=['public'] 或 exclude_operations=[...]
  • 没有 operation_id 的路由会生成类似 read_item_items__item_id__get 这样的名字——很丑 — 始终为路由设置显式 operation_id：@app.get('/items/{id}', operation_id='get_item')
搭配使用： fastmcp

将认证的 FastAPI 应用暴露为 MCP，同时保持认证功能

👤 在 FastAPI 上使用 bearer/OAuth2 认证的后端开发者 ⏱ ~30 min intermediate

何时使用： 你的 FastAPI 路由使用 Depends(get_current_user)——你需要通过 MCP 调用时它仍然触发。

前置条件
  • 现有的认证依赖 — Depends(oauth2_scheme) 或等价的实现
步骤
  1. 传递 Authorization 头
    配置 fastapi-mcp 将 Authorization 头从 MCP 上下文转发到底层路由。指向我相关的设置。✓ 已复制
    → 配置已改变；路由现在接收头信息
  2. 测试认证调用
    通过 MCP 调用受保护端点。先不带 token（期望 401），然后用有效的（期望 200）。✓ 已复制
    → 401 未认证，200 已认证——与直接 HTTP 相同
  3. 文档化客户端设置
    编写用户需要的 mcp-remote 配置，以便他们的 Claude Desktop 传递 Authorization 头。✓ 已复制
    → 可复制粘贴的客户端配置片段

结果： 认证的执行方式相同，无论是从 curl 还是从智能体调用。

注意事项
  • 智能体意外使用了长期有效的根 token — 为每个用户生成短期有效的限域 token；频繁轮换——像对待任何其他 API 客户端一样对待 MCP

将 MCP 端点与现有 API 一起部署

👤 平台工程师 ⏱ ~45 min advanced

何时使用： 你在 Cloud Run / Fly / Render 上运行 FastAPI。你想 MCP 共享那个部署。

步骤
  1. 在稳定路径挂载
    在 /mcp 挂载 fastapi-mcp。确认 /docs（Swagger）和 /mcp 都能在同一进程中工作。✓ 已复制
    → 两个路径都有响应
  2. 通过现有 ingress 暴露
    更新我的 Cloud Run / nginx / API 网关配置，将 /mcp 路由到此服务，配置 SSE 兼容的超时（无缓冲、长空闲）。✓ 已复制
    → 远程 mcp-remote 连接顺利
  3. 文档化客户端设置
    编写面向团队的 README：如何将此 MCP 添加到 Claude Desktop + Cursor。✓ 已复制
    → 每个客户端都有可复制粘贴的配置

结果： 一个部署，两种协议（REST + MCP），零额外基础设施。

注意事项
  • 代理缓冲 SSE 响应，连接似乎挂起 — 禁用代理缓冲——nginx：proxy_buffering off；Cloud Run：已无问题；Cloudflare：启用流式传输
搭配使用： cloud-run · vercel

组合

与其他 MCP 搭配，撬动十倍杠杆

fastapi-mcp + fastmcp

为传统路由使用 fastapi-mcp，为同一进程中的绿地智能体专用工具使用 FastMCP

为我现有的 /api/* 路由挂载 fastapi-mcp，并为仅智能体的操作（如 bulk_sync）注册 3 个新的 FastMCP 工具。✓ 已复制
fastapi-mcp + cloud-run

在 Cloud Run 上一起部署 REST + MCP

以我的 FastAPI 服务为基础，添加 fastapi-mcp，容器化，并部署到 Cloud Run，在 /mcp 使用 IAM 认证。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
FastApiMCP(app, **options) app: FastAPI, include_operations?, exclude_operations?, include_tags?, exclude_tags?, name?, description? 构建时连接——在启动时创建一次 free
.mount(path='/mcp') path? 实例化后立即调用 free
Auto-generated tools derived from each FastAPI route's request/response models 无需操作——挂载后自动出现 与你的路由相同

成本与限制

运行它的成本

API 配额
继承自你的 API
每次调用 Token 数
与直接 HTTP 调用相同——无额外开销
费用
免费，开源
提示
从 MCP 中排除冗长的管理/调试路由——它们会污染智能体的工具列表，并在每次 list_tools 时消耗 token

安全

权限、密钥、影响范围

凭据存储： 无论你的 FastAPI 使用什么——fastapi-mcp 不会添加新的认证层
数据出站： 无论你的路由原本去往哪里

故障排查

常见错误与修复

工具出现，但调用返回 422 验证错误

你的路由使用 dict 而不是 Pydantic BaseModel——MCP 传递类型化的 JSON，你的路由无法解析。重构为 BaseModel。

路由存在于 /items，但没有匹配的工具

fastapi-mcp 在某些情况下会跳过没有 response_model 或 operation_id 的路由。添加 response_model=ItemOut 和 operation_id='get_item'。

验证： curl http://localhost:8000/openapi.json | jq '.paths'
通过 MCP 调用时认证依赖不触发

在 FastApiMCP 选项中配置头转发。如果你的依赖读取 cookie 而不是头，切换到基于头的认证——MCP 没有 cookie jar。

SSE 在 nginx 后挂起

将 proxy_buffering off; proxy_cache off; proxy_read_timeout 3600s; 添加到 /mcp location 块。

替代方案

FastAPI MCP 对比其他方案

替代方案何时用它替代权衡
FastMCP绿地——没有现有 FastAPI 应用，只是编写 MCP 服务器为新项目提供更清晰的开发体验；fastapi-mcp 在改造方面更胜一筹
Hand-written SDK server你需要对工具名称、描述和模式进行细粒度控制更多代码，更多维护——通常不值得

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills