FastAPI-MCP转换器

功能

• 直接集成 - 直接将 MCP 服务器挂载到您的 FastAPI 应用
• 零配置 - 只需指向您的 FastAPI 应用即可工作
• 自动发现 所有 FastAPI 端点并转换为 MCP 工具
• 保留模式 您的请求模型和响应模型
• 保留文档 所有端点的文档，就像在 Swagger 中一样
• 灵活部署 - 将您的 MCP 服务器挂载到同一个应用上，或者单独部署

安装

我们推荐使用 uv，一个快速的 Python 包安装器：

uv add fastapi-mcp

或者，您也可以使用 pip 进行安装：

pip install fastapi-mcp

基本用法

使用 FastAPI-MCP 的最简单方法是直接将 MCP 服务器添加到您的 FastAPI 应用程序中：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(
    app,

    # Optional parameters
    name="My API MCP",
    description="My API description",
    base_url="http://localhost:8000",
)

# Mount the MCP server directly to your FastAPI app
mcp.mount()

就这样！您的自动生成的 MCP 服务器现在可以在 https://app.base.url/mcp 上访问。

关于 base_url 的注意事项：虽然 base_url 是可选的，但我们强烈建议明确提供它。base_url 告诉 MCP 服务器在调用工具时向哪里发送 API 请求。如果不提供，库会尝试自动确定 URL，这在内部和外部 URL 不同的部署环境中可能无法正常工作。

工具命名

FastAPI-MCP 使用 FastAPI 路由中的 operation_id 作为 MCP 工具名称。如果您没有指定 operation_id，FastAPI 会自动生成一个，但这可能会比较晦涩。

比较以下两个端点定义：

# Auto-generated operation_id (something like "read_user_users__user_id__get")
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# Explicit operation_id (tool will be named "get_user_info")
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

为了使工具名称更清晰、更直观，我们建议在 FastAPI 路由定义中显式添加 operation_id 参数。

要了解更多，请阅读 FastAPI 官方文档中的 路径操作的高级配置。

高级用法

FastAPI-MCP 提供了多种方式来自定义和控制您的 MCP 服务器的创建和配置。以下是一些高级用法模式：

自定义 Schema 描述

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

mcp = FastApiMCP(
    app,
    name="My API MCP",
    base_url="http://localhost:8000",
    describe_all_responses=True,     # Include all possible response schemas in tool descriptions
    describe_full_response_schema=True  # Include full JSON schema in tool descriptions
)

mcp.mount()

自定义暴露的端点

您可以使用 Open API 操作 ID 或标签来控制哪些 FastAPI 端点作为 MCP 工具暴露出来：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

# Only include specific operations
mcp = FastApiMCP(
    app,
    include_operations=["get_user", "create_user"]
)

# Exclude specific operations
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user"]
)

# Only include operations with specific tags
mcp = FastApiMCP(
    app,
    include_tags=["users", "public"]
)

# Exclude operations with specific tags
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "internal"]
)

# Combine operation IDs and tags (include mode)
mcp = FastApiMCP(
    app,
    include_operations=["user_login"],
    include_tags=["public"]
)

mcp.mount()

关于过滤的注意事项：

• 您不能同时使用 include_operations 和 exclude_operations
• 您不能同时使用 include_tags 和 exclude_tags
• 您可以结合操作过滤和标签过滤（例如，使用 include_operations 与 include_tags）
• 当结合过滤器时，将采用贪婪的方法。匹配任一条件的端点都将被包括在内

从原始 FastAPI 应用程序中单独部署

您不限于在创建 MCP 的同一 FastAPI 应用程序上提供 MCP 服务。

您可以从一个 FastAPI 应用程序创建 MCP 服务器，并将其挂载到另一个应用程序上：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Your API app
api_app = FastAPI()
# ... define your API endpoints on api_app ...

# A separate app for the MCP server
mcp_app = FastAPI()

# Create MCP server from the API app
mcp = FastApiMCP(
    api_app,
    base_url="http://api-host:8001",  # The URL where the API app will be running
)

# Mount the MCP server to the separate app
mcp.mount(mcp_app)

# Now you can run both apps separately:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000

在创建 MCP 服务器后添加端点

如果您在创建 MCP 服务器之后向 FastAPI 应用程序中添加了端点，则需要刷新服务器以包含这些新端点：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
# ... define initial endpoints ...

# Create MCP server
mcp = FastApiMCP(app)
mcp.mount()

# Add new endpoints after MCP server creation
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Hello, world!"}

# Refresh the MCP server to include the new endpoint
mcp.setup_server()

示例

请参阅 examples 目录中的完整示例。

使用 SSE 连接到 MCP 服务器

一旦您的集成 MCP 的 FastAPI 应用程序运行起来，您可以使用支持 SSE 的任何 MCP 客户端连接到它，比如 Cursor：

1. 运行您的应用程序。

2. 在 Cursor -> 设置 -> MCP 中，使用您的 MCP 服务器端点 URL（例如 http://localhost:8000/mcp）作为 sse。

3. Cursor 将自动发现所有可用的工具和资源。

使用 mcp-proxy stdio 连接到 MCP 服务器

如果您的 MCP 客户端不支持 SSE，例如 Claude Desktop：

1. 运行您的应用程序。

2. 安装 mcp-proxy，例如：uv tool install mcp-proxy。

3. 在 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 的路径。

1. Claude Desktop 将自动发现所有可用的工具和资源

开发与贡献

感谢您考虑为 FastAPI-MCP 做出贡献！我们鼓励社区发布问题和拉取请求。

在开始之前，请参阅我们的 贡献指南。

社区

加入 MCParty Slack 社区，与其他 MCP 爱好者联系，提问并分享您使用 FastAPI-MCP 的经验。

要求

• Python 3.10+（推荐 3.12）
• uv

许可证

MIT 许可证。版权所有 (c) 2024 Tadata Inc.