FastAPI-MCP：让AI轻松“对话”你的后端服务

🌟 FastAPI-MCP：让AI轻松"对话"你的后端服务

大家好！今天我们来聊聊一个能让AI智能体（比如Claude、GPTs）直接调用你现有FastAPI接口的神奇工具------FastAPI-MCP。如果你想让AI帮你操作自己的应用数据，但又不想写一堆适配代码，那这篇文章就是为你准备的！

🤔 什么是MCP？为什么需要FastAPI-MCP？

想象一下，你开发了一个功能完善的FastAPI应用，里面有用户管理、订单处理等各种接口。现在，你想让Claude等AI助手能根据你的指令，比如"帮我查一下用户张三的订单"，直接去调用你的后端接口。这中间的"翻译"工作，就可以交给MCP。

MCP（Model Context Protocol）是Anthropic提出的一种新兴开放协议，它就像一套标准的"对话规则"，让不同的AI助手能够以统一的方式理解和使用外部工具（比如你的API）。

而 FastAPI-MCP ，本质上是一个超级适配器。它不用你修改现有的业务逻辑代码，就能自动将你熟悉的FastAPI路由，转换成AI能理解并调用的MCP工具。

简单比喻：你的FastAPI应用好比一个只会说中文的专家，AI助手是个只会说英文的经理。FastAPI-MCP就是中间那位专业翻译官，让两人沟通无障碍。

⚡️ 核心魅力：三行代码的魔法

看了官方文档，最震撼的一点就是它的简洁。从零到拥有一个带认证的MCP服务器，真的只需要三行核心代码：

python 复制代码

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP  # 1. 导入翻译官

app = FastAPI()  # 2. 这是你原本的FastAPI应用

mcp = FastApiMCP(app)  # 3. 把应用交给翻译官
mcp.mount_http()        #   翻译官开始工作，挂载MCP路由

执行上述代码后，你的MCP服务器就会在 https://你的应用地址/mcp 自动生成并待命。AI助手通过这个入口，就能发现和使用你暴露的所有接口工具。

🛠️ 主要特性详解（为什么它很棒）

内置身份验证，无缝安全过渡

这是最大的亮点之一！你的FastAPI应用可能已经用 Depends() 设置了复杂的权限验证（如OAuth2、JWT）。FastAPI-MCP会直接继承这些安全规则。AI在调用你的接口时，也必须满足同样的登录或权限要求，安全零妥协。
纯正FastAPI血统，非简单转换器

它并非一个将OpenAPI文档硬转成MCP格式的外部工具，而是深度集成在FastAPI ASGI框架内部。这意味着更高效的内部通信和更原生的行为表现。
真正的"零配置"

你不需要为每个接口写描述、定义输入输出模型给AI看。FastAPI-MCP会自动读取你已有的Pydantic请求/响应模型 、接口文档字符串，并原样保留其结构和约束，直接转化为MCP工具的定义。你在Swagger UI里看到什么样，AI拿到的工具说明就是什么样。
灵活的部署方式
- 方式A（同应用挂载） ：如上面的例子，将MCP服务器挂载到你主应用的 /mcp 路径下，部署简单。
- 方式B（独立部署）：你也可以将MCP服务器作为一个独立的ASGI应用启动，实现与主服务的物理分离，灵活性更高。

📖 从零开始使用指南（小白友好）

让我们写一个完整的例子，假设我们有一个管理图书的简单API。

第1步：安装

bash 复制代码

pip install fastapi-mcp

第2步：创建你的FastAPI应用并集成MCP

python 复制代码

# main.py
from fastapi import FastAPI, Depends, HTTPException
from pydantic import BaseModel
from typing import List
from fastapi_mcp import FastApiMCP

# --- 以下是你的常规FastAPI代码 ---
app = FastAPI(title="图书管理系统")

# 1. 定义数据模型
class Book(BaseModel):
    id: int
    title: str
    author: str

class BookCreate(BaseModel):
    title: str
    author: str

# 一个简易的"数据库"
fake_books_db = []
# --- 你的常规代码结束 ---

# --- 核心集成：仅需额外增加这3行 ---
mcp = FastApiMCP(app)
# 你可以选择只暴露特定的路由，例如下面只暴露查询全部图书的接口
# mcp = FastApiMCP(app, include_routes=["get_books"])
mcp.mount_http()
# --- 集成完毕 ---

# --- 定义你的路由 ---
@app.get("/books", response_model=List[Book], summary="获取所有图书", tags=["图书"])
async def get_books():
    """这个接口可以返回系统中所有的图书列表。"""
    return fake_books_db

@app.post("/books", response_model=Book, summary="创建新图书", tags=["图书"])
async def create_book(book: BookCreate):
    """传入标题和作者，创建一本新图书。"""
    new_id = len(fake_books_db) + 1
    new_book = Book(id=new_id, **book.dict())
    fake_books_db.append(new_book)
    return new_book

# 假设这个接口需要认证，我们不希望AI随意调用
def verify_token(token: str = Depends(...)):
    # 复杂的认证逻辑...
    pass

@app.delete("/books/{book_id}", dependencies=[Depends(verify_token)])
async def delete_book(book_id: int):
    # 删除逻辑...
    pass

第3步：运行你的应用

bash 复制代码

uvicorn main:app --reload

现在，访问 http://127.0.0.1:8000/docs 可以看到你的Swagger API文档。

同时，你的MCP服务器已在 http://127.0.0.1:8000/mcp 就绪。

第4步：在AI平台配置

以Claude Desktop为例，编辑其配置文件（claude_desktop_config.json）：

json 复制代码

{
  "mcpServers": {
    "my_book_app": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/serve-fasthttp",
        "http://127.0.0.1:8000/mcp"
      ]
    }
  }
}

重启Claude后，AI就能看到并使用 get_books 和 create_book 这两个工具了！你可以直接说："请调用我的图书API，帮我创建一本名为《FastAPI-MCP指南》的书，作者是我。"

💡 总结与最佳实践

什么时候该用FastAPI-MCP？

你已有成熟的FastAPI项目，想快速赋予AI调用能力。
你重视API的安全性，希望AI调用也遵循既有的严格认证。
你不想维护两套定义（一套OpenAPI，一套给AI的工具定义）。

最佳实践提示：

精心设计工具名 ：虽然工具名默认由路由函数名生成，但你可以在装饰器中使用 summary 参数，让AI更清楚工具用途。
善用"包含"与"排除" ：通过 include_routes 或 exclude_routes 参数，严格控制哪些接口对AI可见。像 delete_book 这种高危操作，通常不建议暴露。
写好文档字符串 ：你在端点下写的"""文档"""，会成为AI理解工具功能的主要依据，请清晰描述。

FastAPI-MCP极大地降低了AI Agent与后端服务集成的门槛。它尊重你现有的代码和架构，以最小侵入的方式，为你的应用打开了通向AI世界的大门。现在就去试试，让你的API和AI开始对话吧！

（本文基于FastAPI-MCP官方文档，日期：2026年2月。具体使用请以项目最新文档为准。）