FastAPI-MCP

Características

Integración directa : monte un servidor MCP directamente en su aplicación FastAPI
No requiere configuración : simplemente apúntelo a su aplicación FastAPI y funcionará
Detección automática de todos los puntos finales de FastAPI y conversión a herramientas MCP
Preservación de esquemas de sus modelos de solicitud y modelos de respuesta
Conserve la documentación de todos sus puntos finales, tal como está en Swagger
Implementación flexible : monte su servidor MCP en la misma aplicación o impleméntelo por separado

Instalación

Recomendamos utilizar uv , un instalador rápido de paquetes de Python:

uv add fastapi-mcp

Alternativamente, puedes instalarlo con pip:

pip install fastapi-mcp

Uso básico

La forma más sencilla de utilizar FastAPI-MCP es agregar un servidor MCP directamente a su aplicación 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()

¡Listo! Tu servidor MCP generado automáticamente ya está disponible en https://app.base.url/mcp .

Nota sobre base_url : Aunque base_url es opcional, se recomienda proporcionarla explícitamente. Esta base_url indica al servidor MCP dónde enviar las solicitudes de API cuando se invocan las herramientas. Sin ella, la biblioteca intentará determinar la URL automáticamente, lo que podría no funcionar correctamente en entornos implementados donde las URL internas y externas difieren.

Nombre de la herramienta

FastAPI-MCP usa el operation_id de sus rutas FastAPI como nombre de las herramientas MCP. Si no especifica un operation_id , FastAPI genera uno automáticamente, pero estos pueden ser crípticos.

Compare estas dos definiciones de puntos finales:

# 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}

Para obtener nombres de herramientas más claros e intuitivos, recomendamos agregar parámetros operation_id explícitos a las definiciones de ruta FastAPI.

Para obtener más información, lea la documentación oficial de FastAPI sobre la configuración avanzada de operaciones de ruta.

Uso avanzado

FastAPI-MCP ofrece varias maneras de personalizar y controlar la creación y configuración de su servidor MCP. A continuación, se muestran algunos patrones de uso avanzados:

Personalización de la descripción del esquema

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()

Personalización de puntos finales expuestos

Puede controlar qué puntos finales de FastAPI se exponen como herramientas MCP mediante identificadores o etiquetas de operaciones de Open API:

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()

Notas sobre el filtrado:

No puedes usar include_operations y exclude_operations al mismo tiempo
No puedes usar include_tags y exclude_tags al mismo tiempo
Puede combinar el filtrado de operaciones con el filtrado de etiquetas (por ejemplo, utilice include_operations con include_tags )
Al combinar filtros, se adoptará un enfoque ambicioso. Se incluirán los puntos finales que cumplan cualquiera de los criterios.

Implementación por separado de la aplicación FastAPI original

No está limitado a servir el MCP en la misma aplicación FastAPI desde la que se creó.

Puede crear un servidor MCP desde una aplicación FastAPI y montarlo en una aplicación diferente:

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

Agregar puntos finales después de la creación del servidor MCP

Si agrega puntos finales a su aplicación FastAPI después de crear el servidor MCP, deberá actualizar el servidor para incluirlos:

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()

Ejemplos

Consulte el directorio de ejemplos para ver ejemplos completos.

Conexión al servidor MCP mediante SSE

Una vez que su aplicación FastAPI con integración MCP esté en ejecución, puede conectarse a ella con cualquier cliente MCP compatible con SSE, como Cursor:

Ejecute su aplicación.
En Cursor -> Configuración -> MCP, use la URL del punto final de su servidor MCP (por ejemplo, http://localhost:8000/mcp ) como sse.
El cursor descubrirá automáticamente todas las herramientas y recursos disponibles.

Conexión al servidor MCP mediante mcp-proxy stdio

Si su cliente MCP no admite SSE, por ejemplo Claude Desktop:

Ejecute su aplicación.
Instale mcp-proxy , por ejemplo: uv tool install mcp-proxy .
Agregue el archivo de configuración MCP de Claude Desktop ( claude_desktop_config.json ):

En Windows:

{
  "mcpServers": {
    "my-api-mcp-proxy": {
        "command": "mcp-proxy",
        "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

En MacOS:

{
  "mcpServers": {
    "my-api-mcp-proxy": {
        "command": "/Full/Path/To/Your/Executable/mcp-proxy",
        "args": ["http://127.0.0.1:8000/mcp"]
    }
  }
}

Encuentre la ruta a mcp-proxy ejecutando en la Terminal: which mcp-proxy .

Claude Desktop descubrirá automáticamente todas las herramientas y recursos disponibles

Desarrollo y contribución

Gracias por considerar contribuir a FastAPI-MCP. Animamos a la comunidad a publicar incidencias y solicitudes de incorporación de cambios.

Antes de comenzar, consulte nuestra Guía de contribuciones .

Comunidad

Únase a la comunidad Slack de MCParty para conectarse con otros entusiastas de MCP, hacer preguntas y compartir sus experiencias con FastAPI-MCP.

Requisitos

Python 3.10+ (recomendado 3.12)
ultravioleta