2025-08-28 新闻动态 63
作为天天和 API 打交道的 Python 开发者，最近挖到一个宝藏开源项目——FastAPI MCP！简直是懒人福音，今天手把手教你用它提升开发效率 10 倍 ✨
✨ 功能亮点速览
为什么说它是神器？这几个功能直接戳中痛点！
🔒 内置认证系统：无需手动写 JWT/Token，开箱即用的安全防护
⚙️ 零配置启动：一行代码挂载，省去复杂配置步骤
📌 保留模式：自动保留 FastAPI 原生特性，学习成本几乎为 0
📚 自动生成文档：自带 Swagger UI 和 ReDoc，API 调试超方便
🔄 动态热更新：新增接口无需重启服务，实时同步到工具列表
📝 3 步快速上手
1️⃣ 安装依赖
pip install fastapi fastapi-mcp uvicorn
# 或使用更快的 uv 包管理器
uv add fastapi fastapi-mcp uvicorn
（记得用 Python 3.8+ 环境哦～）
2️⃣ 基础代码示例
新建 main.py，复制这段极简代码：
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# 创建 FastAPI 实例
app = FastAPI(title="My MCP API")
# 挂载 MCP 服务器（核心步骤！）
mcp = FastApiMCP(
app,
name="My First MCP Server",
description="A demo server for FastAPI-MCP",
base_url="http://localhost:8000" # 强烈建议显式指定基础URL
)
mcp.mount() # 默认挂载到 /mcp 路径
# 定义一个测试路由
@app.get("/", operation_id="read_root") # 显式指定 operation_id 便于 AI 识别
def read_root():
return {"message": "Hello FastAPI MCP! 🎉"}
# 启动服务器
if __name__ == "__main__":
import uvicorn
uvicorn.run("main:app", reload=True)
3️⃣ 启动服务
python main.py
访问 http://localhost:8000/docs，就能看到自动生成的 Swagger 文档啦！🚀
访问 http://localhost:8000/mcp，可查看 MCP 服务状态页
🔐 认证系统详解
基础 Token 认证
from fastapi import Header, HTTPException
from fastapi_mcp import FastApiMCP, AuthConfig
# 自定义认证依赖
async def verify_token(authorization: str = Header(None)):
valid_tokens = {"SECRET_TOKEN_123"} # 实际项目中从环境变量读取
if authorization not in valid_tokens:
raise HTTPException(status_code=403, detail="Invalid token")
return True
# 配置带认证的 MCP 服务器
mcp = FastApiMCP(
app,
auth_config=AuthConfig(
dependencies=[verify_token] # 注入认证依赖
)
)
OAuth2 集成（以 Auth0 为例）
# 安装额外依赖
# pip install python-jose[cryptography] python-multipart
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
async def verify_oauth_token(token: str = Depends(oauth2_scheme)):
try:
payload = jwt.decode(
token,
SECRET_KEY,
algorithms=[ALGORITHM],
audience=API_AUDIENCE,
issuer=ISSUER
)
return payload
except JWTError:
raise HTTPException(status_code=401, detail="Invalid credentials")
⚙️ 高级配置指南
接口筛选与管理
通过 operation_id 或标签精确控制暴露的接口：
# 仅暴露指定 operation_id 的接口
mcp = FastApiMCP(
app,
include_operations=["get_user", "create_item"] # 白名单模式
)
# 按标签筛选接口
mcp = FastApiMCP(
app,
include_tags=["public", "users"] # 仅包含带这些标签的接口
)
自定义工具名称与描述
@app.get("/users/{user_id}",
operation_id="get_user_info", # 工具名称将使用此 ID
description="获取用户详细信息，支持通过 ID 查询特定用户")
async def read_user(user_id: int):
return {"user_id": user_id, "name": "John Doe"}
独立部署模式
如需将 MCP 服务独立部署（不与 HTTP 服务共用端口）：
# main.py
if __name__ == "__main__":
# 仅启动 MCP 服务，不提供 HTTP 接口
mcp.run(mode="standalone", port=9000)
💼 实际项目案例
案例 1：谷歌图片搜索 MCP 服务
from fastapi import HTTPException
from pydantic import BaseModel
import requests
# 定义请求模型
class ImageSearchRequest(BaseModel):
keyword: str
num: int = 5
# 谷歌图片搜索接口
@app.post("/search/images", operation_id="search_google_images")
async def search_images(req: ImageSearchRequest):\n # 实际项目中替换为真实 API 调用
return {\n "images": [\n {"url": f"https://example.com/{req.keyword}_{i}.jpg", "title": f"{req.keyword} image {i}"} \n for i in range(req.num)\n ]\n }
启动后在 Cherry Studio 等 MCP 客户端中配置 http://localhost:8000/mcp，即可让 AI 直接调用图片搜索功能！
案例 2：数据库查询工具集成
from sqlalchemy.orm import Session
from fastapi import Depends
# 数据库依赖
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
# 暴露数据库查询工具
@app.get("/db/query", operation_id="query_database")
async def query_db(sql: str, db: Session = Depends(get_db)):
try:
result = db.execute(sql).fetchall()
return {"columns": result.keys(), "data": result}
except Exception as e:
raise HTTPException(status_code=400, detail=str(e))
⚡ 性能优化技巧
1. 使用异步依赖提升并发
from fastapi import Depends
import httpx
# 异步 HTTP 客户端依赖
async def get_async_client():
async with httpx.AsyncClient() as client:
yield client
@app.get("/external_data", operation_id="fetch_external_data")
async def fetch_data(client: httpx.AsyncClient = Depends(get_async_client)):
response = await client.get("https://api.example.com/data")
return response.json()
2. 结果缓存减少重复计算
from functools import lru_cache
@lru_cache(maxsize=128)
def expensive_calculation(param: int):
# 模拟耗时计算
return param * 42
@app.get("/calculate", operation_id="calculate_value")
async def calculate(param: int):
return {"result": expensive_calculation(param)}
❗ 常见问题与解决方案
问题 1：初始化未完成时收到请求
错误提示：RuntimeError: Received request before initialization was complete
解决方法：升级依赖并添加初始化完成检查
pip install -U fastapi-mcp
问题 2：工具名称过长导致 400 错误
原因：自动生成的 operation_id 可能超过 64 字符限制
解决方法：显式指定简洁的 operation_id（如上文案例所示）
问题 3：客户端无法发现新增接口
解决方法：调用刷新方法更新工具列表
# 新增接口后执行
mcp.setup_server() # 动态更新服务目录
🚀 使用感受分享
作为用过十几个 FastAPI 扩展的开发者，表示 MCP 最打动我的是 「零侵入性」——既保留了 FastAPI 的简洁优雅✨，又补充了企业级开发必备功能🔒。特别是动态热更新和灵活的权限控制，让我们团队的 AI 工具化改造效率提升了 300%！
适合从小项目快速迭代到生产环境，强烈推荐给追求效率的你！
注：此字段内容整理自 FastAPI-MCP GitHub 项目文档（https://github.com/taorg/fastapi_mcp）
