零配置将 FastAPI 端点一键发布为 MCP 工具FastAPI-MCP 完整实战指南【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcpFastAPI-MCP 是一个零配置工具用于自动将 FastAPI 端点公开为模型上下文协议MCP工具让 Cursor、Claude Desktop 等 AI 客户端直接调用你已有的 API。本指南以项目中文 READMEREADME_zh-CN.md为主线结合仓库源码与示例系统讲解安装、基本用法、工具命名、端点过滤、分离部署、刷新机制与客户端接入读完即可在自己的 FastAPI 服务上落地一套可用的 MCP 服务器。项目定位与核心特性FastAPI-MCP 的目标是直接把 MCP 服务器挂到你的 FastAPI 应用上而非简单的 OpenAPI → MCP 转换器。它强调 FastAPI 原生FastAPI-native主要特性如下直接集成直接将 MCP 服务器挂载到您的 FastAPI 应用。零配置只需指向您的 FastAPI 应用即可工作。自动发现所有 FastAPI 端点自动转换为 MCP 工具。保留模式保留请求模型和响应模型的模式schema。保留文档保留所有端点的文档就像在 Swagger 中一样。灵活部署将 MCP 服务器挂载到同一应用或单独部署。ASGI 传输默认使用 FastAPI 的 ASGI 接口直接通信无需发送真实 HTTP 请求效率更高。从源码结构看核心实现集中在 fastapi_mcp/server.pyFastApiMCP类、fastapi_mcp/openapi/convert.pyOpenAPI 到 MCP 工具的转换以及 fastapi_mcp/transport/HTTP 与 SSE 两种传输层封装下文会逐一展开。环境要求与安装项目要求见 README_zh-CN.md 末尾的要求小节Python 3.10推荐 3.12uv包管理器可选使用 pip 亦可推荐使用 uv 安装uv add fastapi-mcp也可以使用 pippip install fastapi-mcp快速上手三行代码挂载 MCP 服务器使用 FastAPI-MCP 的最简单方式是直接将 MCP 服务器添加到你的 FastAPI 应用中与 docs/getting-started/quickstart.mdx 中的步骤一致from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() mcp FastApiMCP(app) # 直接将 MCP 服务器挂载到您的 FastAPI 应用 mcp.mount()就是这样你的自动生成的 MCP 服务器现在可以在https://app.base.url/mcp访问。配合 uvicorn 启动完整示例参考 examples/01_basic_usage_example.pyfrom fastapi import FastAPI from fastapi_mcp import FastApiMCP import uvicorn app FastAPI() mcp FastApiMCP(app) mcp.mount_http() # 推荐使用 mount_httpHTTP 传输 if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)运行python server.py后MCP 服务地址为http://localhost:8000/mcp。源码层面的说明mount 与 mount_http细心的读者会发现 README 示例用的是mcp.mount()而当前仓库源码fastapi_mcp/server.py中mount()已被标记为Deprecated它会发出DeprecationWarning默认走 SSE 传输并委托给mount_sse()。官方推荐的写法是mount_http()HTTPStreamable HTTP传输mount_path默认为/mcpmount_sse()SSE 传输mount_path默认为/sse。从 fastapi_mcp/server.py 可以看到mount_path会做归一化处理自动补前导/、去掉尾部/并支持传入FastAPI应用或APIRouter若传入的是APIRouter挂载路径会附加到该 router 的 prefix 上。HTTP 传输端点在 fastapi_mcp/server.py 中以api_route注册同时支持GET / POST / DELETE方法底层由 fastapi_mcp/transport/http.py 中的FastApiHttpSessionManager包装 MCP SDK 的StreamableHTTPSessionManager实现。工具命名用 operation_id 掌控 MCP 工具名FastAPI-MCP 使用 FastAPI 路由中的operation_id作为 MCP 工具的名称。如果你不指定operation_idFastAPI 会自动生成一个但这些名称可能比较晦涩。比较以下两个端点定义# 自动生成的 operation_id类似于 read_user_users__user_id__get app.get(/users/{user_id}) async def read_user(user_id: int): return {user_id: user_id} # 显式 operation_id工具将被命名为 get_user_info app.get(/users/{user_id}, operation_idget_user_info) async def read_user(user_id: int): return {user_id: user_id}为了获得更清晰、更直观的工具名称建议在 FastAPI 路由定义中添加显式的operation_id参数FastAPI 官方文档中路径操作的高级配置部分有详细介绍。注意operation_id在整个应用中必须唯一否则会与后续的端点过滤机制产生歧义。在转换层fastapi_mcp/openapi/convert.py每个操作只有拿到operationId才会被转换为工具同时把path、method、parameters、request_body存入operation_map供后续调用工具时发起 HTTP 请求使用。高级用法一自定义服务器元数据与工具描述你可以通过name、description定义 MCP 服务器的名称与描述默认取自app.title与app.description见 fastapi_mcp/server.py并通过两个布尔参数控制工具描述的详细程度对应 docs/configurations/customization.mdx 与 examples/02_full_schema_description_example.pyfrom fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() mcp FastApiMCP( app, name我的 API MCP, describe_all_responsesTrue, # 在工具描述中包含所有可能的响应模式 describe_full_response_schemaTrue # 在工具描述中包含完整的 JSON 模式 ) mcp.mount_http()这两个参数对喂给 LLM 的工具描述质量影响很大其底层逻辑在 fastapi_mcp/openapi/convert.py默认情况下工具描述只列出2XX 成功响应success_codes range(200, 300)并尽量从 schema 生成响应示例当describe_all_responsesTrue时所有状态码的响应4xx、5xx 等都会写进描述当describe_full_response_schemaTrue时描述中包含完整的响应 JSON Schema而不仅仅是示例。对 LLM 而言响应 Schema 越完整调用工具时对返回结构的预判就越准确代价是工具描述更长、token 消耗更大可根据实际需要取舍。高级用法二用 operation_id 与标签精确控制暴露的端点你可以使用 OpenAPI 操作 ID 或标签来控制哪些 FastAPI 端点暴露为 MCP 工具完整示例见 examples/03_custom_exposed_endpoints_example.pyfrom fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() # 仅包含特定操作 mcp FastApiMCP( app, include_operations[get_user, create_user] ) # 排除特定操作 mcp FastApiMCP( app, exclude_operations[delete_user] ) # 仅包含具有特定标签的操作 mcp FastApiMCP( app, include_tags[users, public] ) # 排除具有特定标签的操作 mcp FastApiMCP( app, exclude_tags[admin, internal] ) # 结合操作 ID 和标签包含模式 mcp FastApiMCP( app, include_operations[user_login], include_tags[public] ) mcp.mount()关于过滤的注意事项README 原文务必遵守您不能同时使用include_operations和exclude_operations您不能同时使用include_tags和exclude_tags您可以将操作过滤与标签过滤结合使用例如使用include_operations和include_tags当结合过滤器时将采取贪婪方法——匹配任一标准的端点都将被包含。这些约束并非只是文档建议而是构造函数中的硬性校验在 fastapi_mcp/server.py同时传入include_operations与exclude_operations或同时传入include_tags与exclude_tags会直接抛出ValueError。实际的过滤逻辑由_filter_tools()fastapi_mcp/server.py完成它先从 OpenAPI schema 构建tag - operationId的映射再按包含/排除语义求出应保留的工具集合最后同步裁剪operation_map保证被过滤掉的端点绝不会被调用。examples/03_custom_exposed_endpoints_example.py 还展示了更实战的玩法在同一个 FastAPI 应用上挂载多个不同过滤策略的 MCP 服务器分别暴露在不同路径如/include-operations-mcp、/exclude-tags-mcp、/combined-include-mcp适合按团队、按权限场景拆分工具面。高级用法三将 MCP 服务器与原始 FastAPI 应用分开部署你可以在一个 FastAPI 应用上创建 MCP 服务器然后挂载到另一个应用上参考 examples/04_separate_server_example.pyfrom fastapi import FastAPI from fastapi_mcp import FastApiMCP # 您的 API 应用 api_app FastAPI() # ... 在 api_app 上定义您的 API 端点 ... # 一个单独的 MCP 服务器应用 mcp_app FastAPI() # 从 API 应用创建 MCP 服务器 mcp FastApiMCP(api_app) # 将 MCP 服务器挂载到单独的应用 mcp.mount(mcp_app) # 现在您可以分别运行两个应用 # uvicorn main:api_app --host api-host --port 8001 # uvicorn main:mcp_app --host mcp-host --port 8000从源码看mount_http(router...)与mount_sse(router...)的 docstring 明确写道There is no requirement that the FastAPI app or APIRouter is the same as the one that the MCP server was created from不要求挂载目标与 MCP 服务器的来源应用相同。这种部署模式下MCP 服务器与业务 API 可以独立扩缩容、独立暴露且原始 API 不直接对外只通过 MCP 工具访问。高级用法四创建后新增端点的刷新机制如果你在创建 MCP 服务器后向 FastAPI 应用添加端点需要刷新服务器以包含它们from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() # ... 定义初始端点 ... # 创建 MCP 服务器 mcp FastApiMCP(app) mcp.mount_http() # 在 MCP 服务器创建后添加新端点 app.get(/new/endpoint/, operation_idnew_endpoint) async def new_endpoint(): return {message: Hello, world!} # 刷新 MCP 服务器以包含新端点 mcp.setup_server()原因在于FastApiMCP.__init__会在构造时调用一次setup_server()fastapi_mcp/server.py将当时的路由快照转换为工具列表并注册list_tools/call_tool处理器。此后新增的路由不会自动进入工具列表需要再次调用setup_server()重新生成——它会重新调用get_openapi()拉取最新路由、重新执行 OpenAPI 转换与过滤fastapi_mcp/server.py。examples/05_reregister_tools_example.py 演示了这一场景注释明确指出新增的/new/endpoint/在未刷新前不会注册为工具调用mcp.setup_server()之后才会暴露。高级用法五通信方式与自定义 HTTP 客户端FastAPI-MCP 默认使用ASGI 传输它直接与你的 FastAPI 应用通信而不发送真实 HTTP 请求。更高效也不需要基础 URL。如果你需要指定自定义基础 URL 或使用不同的传输方式可以提供自己的httpx.AsyncClientimport httpx from fastapi import FastAPI from fastapi_mcp import FastApiMCP app FastAPI() # 使用带有特定基础 URL 的自定义 HTTP 客户端 custom_client httpx.AsyncClient( base_urlhttps://api.example.com, timeout30.0 ) mcp FastApiMCP( app, http_clientcustom_client ) mcp.mount()从 fastapi_mcp/server.py 可以看到默认客户端的构造方式使用httpx.ASGITransport(appself.fastapi, raise_app_exceptionsFalse)直连 ASGI 接口base_urlhttp://apiservertimeout10.0。也就是说即使你的 API 应用与 MCP 服务器分开部署工具调用仍然可以通过 ASGI 直连前提是同一进程而传入自定义httpx.AsyncClient后则可以指向任意远程 API 地址。另外值得一提工具执行链路_execute_api_toolfastapi_mcp/server.py会自动把 path 参数回填进 URL、query 参数组装成查询串、header 参数放入请求头剩余参数作为 JSON body 发送同时支持从 MCP 请求上下文提取原始 HTTP 请求信息并按照头部白名单默认仅authorization见构造函数headers[authorization]转发头部这为后续接入认证打下了基础。客户端接入实战一旦集成了 MCP 的 FastAPI 应用运行起来就可以用各种支持 MCP 的客户端连接它。通过 SSE 连接以 Cursor 为例任何支持 SSE 的 MCP 客户端都可以直接连接例如 Cursor运行您的应用在 Cursor → 设置 → MCP 中使用您的 MCP 服务器端点的 URL例如http://localhost:8000/mcp作为 sseCursor 将自动发现所有可用的工具和资源。主流 MCP 客户端Claude Desktop、Cursor、Windsurf通用的配置格式如下见 docs/getting-started/quickstart.mdx{ mcpServers: { fastapi-mcp: { url: http://localhost:8000/mcp } } }通过 mcp-proxy stdio 连接以 Claude Desktop 为例如果您的 MCP 客户端不支持 SSE例如 Claude Desktop可以使用mcp-proxy作为 stdio → SSE 的桥接运行您的应用安装 mcp-proxy例如uv tool install mcp-proxy在 Claude Desktop 的 MCP 配置文件claude_desktop_config.json中添加配置。在Windows上{ mcpServers: { my-api-mcp-proxy: { command: mcp-proxy, args: [http://127.0.0.1:8000/mcp] } } }在MacOS上{ mcpServers: { my-api-mcp-proxy: { command: /Full/Path/To/Your/Executable/mcp-proxy, args: [http://127.0.0.1:8000/mcp] } } }通过在终端运行which mcp-proxy可以找到 mcp-proxy 的可执行文件路径MacOS 上需填写完整路径。Claude Desktop 将自动发现所有可用的工具和资源。如果你的客户端需要认证支持或者你的客户端同样不支持 SSE也可以使用npx mcp-remote作为桥接docs/getting-started/quickstart.mdx 中的配置示例{ mcpServers: { fastapi-mcp: { command: npx, args: [ mcp-remote, http://localhost:8000/mcp, 8080 ] } } }其中8080为可选端口号如果你没有动态客户端注册dynamic client registration又需要 OAuth 正常工作则必须指定它。认证支持复用你已有的 FastAPI 依赖项目简介中特别强调 with Auth!。虽然中文 README 未展开但源码中已内置了完整的 OAuth 认证骨架fastapi_mcp/types.py 定义了AuthConfig支持 MCP 规范版本2025-03-26核心字段包括dependencies复用你已有的 FastAPI 认证依赖Depends()未认证时返回 401/403从而触发客户端启动 OAuth 流程issuerOAuth 2.0 服务器的 issuercustom_oauth_metadata自定义 OAuth 元数据RFC 8414 格式setup_proxies是否自动为 OAuth 提供商的端点搭建 MCP 兼容代理setup_fake_dynamic_registration是否搭建一个伪动态客户端注册端点npx mcp-remote依赖它metadata_pathOAuth 元数据端点挂载路径默认/.well-known/oauth-authorization-server。具体代理实现位于 fastapi_mcp/auth/proxy.py对应示例为 examples/08_auth_example_token_passthrough.py令牌透传与 examples/09_auth_example_auth0.py接入 Auth0。需要注意的是认证相关的配置项较多且相互依赖如setup_proxiesTrue时必须提供client_id建议以 fastapi_mcp/types.py 中AuthConfig的字段注释为准。从源码看一次工具调用的完整链路把 README 的功能串起来一次工具调用的完整链路可以这样理解构建阶段FastApiMCP(app)构造时调用setup_server()fastapi_mcp/server.py用 FastAPI 的get_openapi()生成 OpenAPI 3 文档转换阶段convert_openapi_to_mcp_tools()fastapi_mcp/openapi/convert.py先resolve_schema_references()解析全部$ref引用再遍历每个 path 的 GET/POST/PUT/DELETE/PATCH 操作生成mcp.types.Tool列表与operation_map过滤阶段_filter_tools()fastapi_mcp/server.py按 operation_id 与标签过滤得到最终工具列表调用阶段客户端call_tool触发handle_call_toolfastapi_mcp/server.py_execute_api_tool依据operation_map拼装 path/query/header/body通过默认 ASGI 客户端或自定义httpx.AsyncClient发起请求返回阶段响应 JSON 序列化带缩进、保留中文后包装为types.TextContent4xx/5xx 状态码会被视为错误抛出fastapi_mcp/server.py。此外list_tools处理器直接返回当前self.tools这就是刷新后新工具立即可见的原因。仓库配套资源完整示例examples/ 目录下覆盖基本用法01、完整 schema 描述02、端点过滤03、分离部署04、工具刷新05、自定义 MCP Router06、HTTP 超时配置07、认证透传08与 Auth0 接入09示例共用应用定义在 examples/shared/apps/items.py包含带标签、operation_id 与 docstring 的商品 CRUD 与搜索端点官方文档docs/ 下含快速开始docs/getting-started/quickstart.mdx、配置自定义docs/configurations/customization.mdx、工具命名docs/configurations/tool-naming.mdx以及进阶主题认证、部署、刷新、传输等测试用例tests/ 覆盖基础功能、配置、真实 HTTP/SSE 传输、OpenAPI 转换与类型校验等是理解各参数行为边界的最佳参考资料。小结FastAPI-MCP 的核心价值在于你不需要学习任何新的服务器框架只需把已有的 FastAPI 应用交给FastApiMCP就能在/mcp得到一个自动生成的 MCP 服务器。再结合operation_id命名、include/exclude过滤、setup_server()刷新、分离部署与自定义 HTTP 客户端等高级能力即可在生产中把任意 FastAPI 服务安全、受控地开放给 AI 客户端。动手前请记住三点使用mount_http()/mount_sse()替代已弃用的mount()为每个端点显式声明唯一且语义清晰的operation_id新增路由后调用setup_server()刷新工具列表。【免费下载链接】fastapi_mcpExpose your FastAPI endpoints as Model Context Protocol (MCP) tools, with Auth!项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考