零代码扩展！FastAPI-MCP插件系统让你的API秒变智能工具
项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp 你是否遇到过这样的困境：辛辛苦苦开发的FastAPI接口，想要集成到AI助手或自动化工作流时，却要重复编写大量适配代码？作为开发者，我们都希望自己的API能被更广泛地使用，但传统集成方式往往需要编写大量胶水代码，不仅耗时还容易出错。今天我要向你介绍一个革命性的解决方案——FastAPI-MCP插件系统，它能让你的FastAPI端点零配置转换为模型上下文协议（MCP）工具，轻松集成到各类AI系统中。
读完本文后，你将能够：
- 理解MCP（模型上下文协议）如何改变API集成方式
- 掌握FastAPI-MCP的核心功能和使用方法
- 通过实际案例学习如何过滤和定制MCP工具
- 学会配置认证和安全设置保护你的API
- 了解高级扩展和部署最佳实践
MCP是什么？为什么它如此重要？
模型上下文协议（Model Context Protocol，MCP）是一种新兴的API规范，专为AI模型与外部工具交互设计。与传统API不同，MCP强调：
- 自描述性：工具自动提供详细的能力描述和参数说明
- 上下文感知：支持在对话流程中保持状态
- 多模态交互：不仅支持文本，还能处理图像和其他媒体类型
FastAPI-MCP作为桥梁，能自动将你的FastAPI应用转换为符合MCP规范的工具服务，让AI系统像使用内置函数一样调用你的API。项目核心代码在fastapi_mcp/server.py中实现，通过分析你的FastAPI应用结构，自动生成MCP兼容的接口描述。
快速开始：3行代码让FastAPI支持MCP
FastAPI-MCP的使用极其简单，即使是刚接触FastAPI的开发者也能在几分钟内完成集成。让我们看看最基本的示例：
from examples.shared.apps.items import app # 你的FastAPI应用
from fastapi_mcp import FastApiMCP
# 初始化MCP服务器
mcp = FastApiMCP(app)
# 挂载MCP端点到FastAPI应用
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
这段代码来自examples/01_basic_usage_example.py，它完成了三件事：
- 导入现有的FastAPI应用
- 创建FastApiMCP实例并关联你的应用
- 将MCP服务挂载到FastAPI应用中
启动服务后，你的API就自动获得了MCP能力，默认会在/mcp路径下提供MCP工具列表和调用接口。
定制你的MCP工具集：过滤与配置
不是所有API端点都适合作为MCP工具暴露，FastAPI-MCP提供了灵活的过滤机制，让你精确控制哪些端点被转换为MCP工具。主要过滤方式有两种：按操作ID过滤和按标签过滤。
按操作ID过滤
你可以明确指定包含或排除哪些操作：
# 只包含特定操作ID
include_operations_mcp = FastApiMCP(
app,
name="Item API MCP - Included Operations",
include_operations=["get_item", "list_items"],
)
# 排除特定操作ID
exclude_operations_mcp = FastApiMCP(
app,
name="Item API MCP - Excluded Operations",
exclude_operations=["create_item", "update_item", "delete_item"],
)
按标签过滤
如果你的FastAPI应用使用标签（tags）组织端点，也可以按标签过滤：
# 只包含特定标签的操作
include_tags_mcp = FastApiMCP(
app,
name="Item API MCP - Included Tags",
include_tags=["items"],
)
# 排除特定标签的操作
exclude_tags_mcp = FastApiMCP(
app,
name="Item API MCP - Excluded Tags",
exclude_tags=["search"],
)
组合过滤策略
你还可以组合使用不同的过滤策略，实现更精细的控制：
# 组合操作ID和标签过滤
combined_include_mcp = FastApiMCP(
app,
name="Item API MCP - Combined Include",
include_operations=["delete_item"], # 包含特定操作
include_tags=["search"], # 同时包含特定标签
)
以上示例均来自examples/03_custom_exposed_endpoints_example.py。配置完成后，使用mount_http方法将不同的MCP实例挂载到不同路径：
include_operations_mcp.mount_http(mount_path="/include-operations-mcp")
exclude_operations_mcp.mount_http(mount_path="/exclude-operations-mcp")
include_tags_mcp.mount_http(mount_path="/include-tags-mcp")
exclude_tags_mcp.mount_http(mount_path="/exclude-tags-mcp")
combined_include_mcp.mount_http(mount_path="/combined-include-mcp")
安全配置：保护你的MCP工具
当你的API通过MCP暴露给外部系统时，安全变得尤为重要。FastAPI-MCP提供了完善的认证机制，你可以在初始化时配置认证选项：
from fastapi_mcp.auth.proxy import AuthConfig
# 创建认证配置
auth_config = AuthConfig(
provider="auth0",
client_id="your-client-id",
audience="https://your-api-audience",
# 其他认证相关配置...
)
# 使用认证配置初始化MCP服务器
mcp = FastApiMCP(
app,
auth_config=auth_config,
# 配置要转发的HTTP头
headers=["authorization", "x-request-id"]
)
认证相关的实现位于fastapi_mcp/auth/proxy.py，支持多种认证方式，包括OAuth2和自定义令牌验证。你还可以通过headers参数控制哪些HTTP头会从MCP请求转发到实际的API调用中。
高级功能：传输方式与扩展
FastAPI-MCP支持多种传输方式，以适应不同的使用场景：
服务器发送事件（SSE）传输
除了基本的HTTP传输外，FastAPI-MCP还支持SSE传输，适合需要长时间运行或流式响应的场景：
# 使用SSE传输挂载MCP服务
mcp.mount_sse(mount_path="/sse-mcp")
SSE传输的实现位于fastapi_mcp/transport/sse.py，它使用Server-Sent Events协议提供持续的双向通信通道。
自定义工具描述
FastAPI-MCP会自动从OpenAPI文档生成工具描述，但你也可以通过配置自定义这些描述：
mcp = FastApiMCP(
app,
name="自定义MCP服务名称",
description="这是我的自定义MCP服务描述",
describe_all_responses=True, # 包含所有响应模式
describe_full_response_schema=True # 包含完整响应JSON模式
)
这些参数控制生成的MCP工具描述的详细程度，帮助AI系统更好地理解和使用你的API。
部署与最佳实践
在将集成了FastAPI-MCP的应用部署到生产环境时，有几点最佳实践需要注意：
- 环境配置：通过环境变量或配置文件管理敏感信息，如认证密钥和API地址
- 性能考虑：对于高流量场景，可以配置HTTP客户端的超时和连接池：
import httpx
# 创建自定义HTTP客户端
client = httpx.AsyncClient(
timeout=httpx.Timeout(10.0),
limits=httpx.Limits(max_connections=100)
)
# 使用自定义客户端初始化MCP
mcp = FastApiMCP(app, http_client=client)
- 监控与日志：利用FastAPI的日志功能和MCP的事件系统，监控工具使用情况
- 版本控制：为不同版本的API维护不同的MCP端点，避免兼容性问题
更多部署相关内容可以参考官方文档docs/advanced/deploy.mdx。
总结与展望
FastAPI-MCP彻底改变了FastAPI应用与AI系统集成的方式，通过自动化和标准化，大幅降低了开发门槛。我们学习了如何：
- 使用几行代码为FastAPI添加MCP支持
- 根据操作ID和标签过滤MCP工具
- 配置认证和安全设置
- 选择合适的传输方式
- 遵循部署最佳实践
随着AI技术的发展，MCP协议将成为连接AI模型与外部工具的重要标准。FastAPI-MCP作为先驱实现，正在不断进化，未来还将支持更多功能，如工具调用的权限控制、使用统计分析等。
要了解更多细节，可以查阅完整的官方文档和示例代码。现在就尝试将你的FastAPI应用转换为MCP工具，让它在AI时代发挥更大价值吧！
如果你觉得这篇文章有帮助，请点赞、收藏并关注项目更新。下一篇我们将深入探讨如何在大型项目中组织和管理多个MCP插件，敬请期待！
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
