FastAPI MCP 是什么？怎么使用？一文介绍

本文跟大家聊聊一个非常实用的工具 —— FastAPI MCP。如果你正在使用 FastAPI 开发 API，并且想让你的 API 能够被 AI 模型（比如 GPT、Claude）调用，那这篇文章绝对不容错过。

FastAPI MCP 是什么？

简单来说，FastAPI MCP 是一个零配置工具，它能够自动把你的 FastAPI 接口转换成符合模型上下文协议（Model Context Protocol，简称 MCP）的工具。这样，AI 模型就能够直接调用你的 API 了。

 
说白了，它就是一个桥梁，连接你的 API 和各种 AI 模型，让 AI 能够"看懂"并使用你的 API。这么理解，你可以让 Claude 或 GPT 直接调用你的服务获取数据、处理信息或执行操作，是不是很有趣？

FastAPI MCP 有什么用？

在 AI 应用开发中，我们可能有这样的需求：需要让 AI 模型去调用外部服务。比如：

• 让 AI 查询你的数据库
• 让 AI 调用你的计算服务
• 让 AI 访问你的内部工具
• 其它......

 
以前，这需要专门为 AI 重新开发一套接口，或者写复杂的适配器。现在有了 FastAPI MCP，只需几行代码，你现有的 API 就能被 AI 直接调用，省时又省力！

让我们开始使用 FastAPI MCP

接下来，我会一步步教你如何在本地搭建并测试 FastAPI MCP。

步骤一：准备 Python 环境

第一步就是确保你有一个可用的 Python 环境！这是最基础的要求。

 
如果你还没有安装 Python，可以从 Python 官网 下载并安装最新版本（建议使用 Python 3.10 或更高版本）。

 
安装完成后，可以在命令行验证一下：

python --version
# 或者
python3 --version

如果正确显示版本号（如 Python 3.10.x），那么你的 Python 环境就准备好了！

步骤二：安装必要的包

接下来安装 FastAPI、Uvicorn 和 FastAPI MCP：

pip install fastapi uvicorn fastapi-mcp

步骤三：创建一个简单的 FastAPI 应用

为了避免可能的问题，我们先创建一个非常简单的 FastAPI 应用。创建一个名为 main.py 的文件，内容如下：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI(title="简单 API")

@app.get("/hello", operation_id="say_hello")
async def hello():
    """简单的问候端点"""
    return {"message": "Hello World"}

# 创建 MCP 服务器
mcp = FastApiMCP(app, name="简单 MCP 服务")
mcp.mount()

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="127.0.0.1", port=8000)

这个例子非常简单，只包含一个 /hello 端点，返回一个简单的问候消息。

步骤四：运行并测试应用

现在我们可以运行应用并测试了：

python main.py

或者：

uvicorn main:app --reload

服务器会在 http://127.0.0.1:8000 上启动。

步骤五：探索 MCP 端点

打开浏览器，访问 MCP 端点：http://127.0.0.1:8000/mcp

 
注意：与普通 API 不同，MCP 端点使用的是 Server-Sent Events (SSE) 协议，所以在浏览器中你会看到类似这样的输出：

event: endpoint
data: /mcp/messages/?session_id=a543519a5f3848febfd4f40b5ad3b5c7

这表明 MCP 服务器已经启动，并准备好接收来自 AI 客户端的请求。FastAPI MCP 使用 Server-Sent Events (SSE) 协议，所以在浏览器中会看到这种特殊格式。

在 AI 客户端中连接 FastAPI MCP

现在我们需要将支持 MCP 的 AI 客户端连接到我们的服务器，以 Cursor 为例：

方法一：使用 SSE（Server-Sent Events）连接

大多数流行的 MCP 客户端（Claude Desktop、Cursor 和 Windsurf）都支持 SSE 连接，使用以下配置格式：

{
  "mcpServers": {
    "fastapi-mcp": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

在各个客户端中，你只需要找到相应的设置部分添加此配置。比如在 Curosr 中，你需要点击右上角的设置图标，然后定位到「MCP -> Add new global MCP server」，在打开的 mcp.json 文件中输入上面的 JSON 配置：

只要你的 FastAPI MCP 服务开启，那么在 Cursor 里就能自动启用：

方法二：使用 mcp-remote 作为桥接器

如果你需要支持认证，或者你的 MCP 客户端不支持 SSE，可以使用 mcp-remote 作为桥接器：

{
  "mcpServers": {
    "fastapi-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8000/mcp",
        "8080"  // 可选端口号
      ]
    }
  }
}

在 AI 客户端中使用 FastAPI MCP

在 Cursor 等 AI IDE 中成功连接 FastAPI MCP 后，就可以开始对话了。比如在 Cursor 的 Agent 模式下，我这么问：“帮我调用 /hello 接口”，AI 就会返回接口的输出结果：

进阶使用技巧

在掌握了基础用法后，让我们来看一些进阶技巧，这些技巧可以让你更灵活地使用 FastAPI MCP。

自定义暴露的端点

在实际应用中，你可能不希望所有 API 端点都暴露给 AI 模型。FastAPI MCP 提供了多种方式来控制哪些端点可以被暴露：

# 只暴露特定的操作ID
mcp = FastApiMCP(
    app,
    include_operations=["say_hello", "get_user_info"]
)

# 排除特定的操作ID
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user", "update_settings"]
)

# 只暴露带有特定标签的端点
mcp = FastApiMCP(
    app,
    include_tags=["public", "read_only"]
)

# 排除带有特定标签的端点
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "sensitive"]
)

这种灵活性让你可以精确控制哪些功能对 AI 模型可用，增强了安全性。

添加认证保护

在生产环境中，你可能希望保护你的 MCP 端点，确保只有经过认证的客户端才能访问：

from fastapi import FastAPI, Depends, Security
from fastapi.security import APIKeyHeader

app = FastAPI()
api_key_header = APIKeyHeader(name="X-API-Key")

# 定义一个验证API密钥的函数
async def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key != "your-secret-key":  # 实际应用中应使用环境变量或安全存储
        raise HTTPException(status_code=403, detail="Invalid API key")
    return api_key

# 创建MCP服务器，添加认证依赖
mcp = FastApiMCP(app, mcp_dependencies=[Depends(verify_api_key)])
mcp.mount()

现在，所有对 MCP 服务的请求都需要在头部包含有效的 API 密钥。

自定义响应处理

有时候，你可能想在返回给 AI 模型的响应中包含额外信息或进行格式转换：

from fastapi import FastAPI, Response, Request
from fastapi_mcp import FastApiMCP
from typing import Callable, Dict, Any

app = FastAPI()

# 定义自定义响应处理器
async def response_processor(
    request: Request,
    response: Response,
    response_data: Dict[str, Any]
) -> Dict[str, Any]:
    # 添加元数据或修改响应
    response_data["processed_by"] = "custom_processor"
    response_data["timestamp"] = datetime.now().isoformat()
    return response_data

# 创建MCP服务器，添加响应处理器
mcp = FastApiMCP(
    app,
    response_processor=response_processor
)
mcp.mount()

分离部署

在一些场景下，你可能希望将 MCP 服务器与主 API 服务分开部署：

# api_app.py - 你的主API应用
from fastapi import FastAPI
api_app = FastAPI()

@api_app.get("/data")
def get_data():
    return {"data": "some value"}

# mcp_app.py - 单独的MCP服务器应用
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
from api_app import api_app  # 导入主API应用

mcp_app = FastAPI()
mcp = FastApiMCP(api_app)
mcp.mount(mcp_app)  # 挂载到mcp_app而不是api_app

# 现在可以分别运行两个应用：
# uvicorn api_app:api_app --port 8001
# uvicorn mcp_app:mcp_app --port 8000

这种方式让你可以独立扩展 MCP 服务，或者为不同的 API 应用提供统一的 MCP 接入点。

注意事项

使用 FastAPI MCP 时，有协议安全性问题考虑：

1. 限制暴露的端点：只暴露安全的、只读的端点，避免暴露可能造成系统变更的端点（如 DELETE、PUT 操作）。
2. 添加适当的认证：确保只有授权用户才能通过 AI 访问你的 API。
3. 请求验证：利用 FastAPI 的 Pydantic 模型进行严格的请求参数验证。
4. 响应过滤：考虑过滤掉响应中的敏感信息，尤其是当 AI 模型可能将这些信息显示给用户时。

总结

使用 FastAPI MCP 真的非常简单！只要你有 Python 环境，几分钟内就能把你的 API 转变为 AI 可调用的工具。整个过程可以概括为：

1. 安装 Python
2. 安装必要的包
3. 创建 FastAPI 应用
4. 添加 MCP 支持
5. 在 AI IDE 中运行并测试 FastAPI MCP

这个工具最大的优势就是"零配置"，它能自动将你现有的 API 转换成符合 MCP 规范的工具，不需要你重写任何代码。如果你想了解更多高级功能，可以查看 GitHub 上的官方文档。

其它好用的 MCP Server 推荐

Apifox MCP Server 能够将 Apifox 的 API 文档提供给 Cursor 等支持 AI 编程的 IDE 或其他支持 MCP 的 AI 工具。它支持多种使用场景：既可以连接到 Apifox 项目内的 API 文档，也可以访问公开发布的 API 文档，还支持 OpenAPI/Swagger 文档。

安装配置非常简单，只需要 Node.js 环境（版本号≥18），然后根据不同场景选择配置方法。对于私有化部署的用户，还可以添加自定义 API 基础地址。使用 Apifox MCP Server，开发者可以通过 AI 助手完成根据接口文档生成代码、修改代码、搜索接口文档内容等工作，极大提高开发效率。

在实际使用中，你只需要告诉 AI 你想要通过 API 文档做什么，比如"根据 API 文档，生成接口/users 相关的所有 MVC 代码"，AI 就能理解并完成任务。对于团队协作开发尤为有用，确保所有开发者都能基于统一的 API 文档标准进行开发。

Cursor + Apifox MCP Server：借助 AI 与 API 文档高效编写代码

了解更多：

• Trae 中怎么使用 MCP？图文教程
• 一文搞懂什么是 Vibe Coding？以及推荐的工具？
• FastMCP 是什么？怎么在本地搭建？图文教程指南！