FastAPI-MCP

Una herramienta de configuración cero para exponer automáticamente endpoints de FastAPI como herramientas MCP.

GitHub
1
Prueba este MCPPatrocinado

Documentación

fastapi-to-mcp

FastAPI-MCP

Una herramienta de configuración cero para exponer automáticamente los endpoints de FastAPI como herramientas del Model Context Protocol (MCP).

PyPI version Python Versions FastAPI CI codecov

fastapi-mcp-usage

Características

  • Integración directa - Monta un servidor MCP directamente en tu aplicación FastAPI
  • Configuración cero requerida - solo apunta a tu aplicación FastAPI y funciona
  • Descubrimiento automático de todos los endpoints de FastAPI y conversión a herramientas MCP
  • Preservación de esquemas de tus modelos de solicitud y modelos de respuesta
  • Preservación de documentación de todos tus endpoints, tal como está en Swagger
  • Despliegue flexible - Monta tu servidor MCP en la misma aplicación, o despliega por separado

Instalación

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

uv add fastapi-mcp

Alternativamente, puedes instalar con pip:

pip install fastapi-mcp

Uso Básico

La forma más sencilla de usar FastAPI-MCP es añadir un servidor MCP directamente a tu 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()

¡Eso es todo! Tu servidor MCP auto-generado ahora está disponible en https://app.base.url/mcp.

Nota sobre base_url: Aunque base_url es opcional, se recomienda encarecidamente proporcionarlo explícitamente. El base_url le dice al servidor MCP dónde enviar las solicitudes de API cuando se llaman las herramientas. Sin él, la biblioteca intentará determinar la URL automáticamente, lo que puede no funcionar correctamente en entornos desplegados donde las URLs internas y externas difieren.

Nombres de Herramientas

FastAPI-MCP usa el operation_id de tus rutas FastAPI como nombres de herramientas MCP. Cuando no especificas un operation_id, FastAPI genera uno automáticamente, pero estos pueden ser crípticos.

Compara estas dos definiciones de endpoints:

# 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 nombres de herramientas más claros e intuitivos, recomendamos añadir parámetros operation_id explícitos a tus definiciones de rutas FastAPI.

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

Uso Avanzado

FastAPI-MCP proporciona varias formas de personalizar y controlar cómo se crea y configura tu servidor MCP. Aquí hay algunos patrones de uso avanzado:

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

Personalizando Endpoints Expuestos

Puedes controlar qué endpoints de FastAPI se exponen como herramientas MCP usando IDs de operación de Open API o etiquetas:

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 tanto include_operations como exclude_operations al mismo tiempo
  • No puedes usar tanto include_tags como exclude_tags al mismo tiempo
  • Puedes combinar el filtrado por operación con el filtrado por etiqueta (por ejemplo, usar include_operations con include_tags)
  • Al combinar filtros, se tomará un enfoque codicioso. Se incluirán los endpoints que coincidan con cualquiera de los criterios

Desplegando por Separado de la Aplicación FastAPI Original

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

Puedes 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

Añadiendo Endpoints Después de la Creación del Servidor MCP

Si añades endpoints a tu aplicación FastAPI después de crear el servidor MCP, necesitarás 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

Consulta el directorio de ejemplos para ver ejemplos completos.

Conectándose al Servidor MCP usando SSE

Una vez que tu aplicación FastAPI con integración MCP esté en ejecución, puedes conectarte a ella con cualquier cliente MCP que soporte SSE, como Cursor:

  1. Ejecuta tu aplicación.

  2. En Cursor -> Configuración -> MCP, usa la URL de tu endpoint del servidor MCP (por ejemplo, http://localhost:8000/mcp) como sse.

  3. Cursor descubrirá automáticamente todas las herramientas y recursos disponibles.

Conectándose al Servidor MCP usando mcp-proxy stdio

Si tu cliente MCP no soporta SSE, por ejemplo Claude Desktop:

  1. Ejecuta tu aplicación.

  2. Instala mcp-proxy, por ejemplo: uv tool install mcp-proxy.

  3. Añade en 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"]
    }
  }
}

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

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

Desarrollo y Contribuciones

¡Gracias por considerar contribuir a FastAPI-MCP! Animamos a la comunidad a publicar Issues y Pull Requests.

Antes de comenzar, consulta nuestra Guía de Contribución.

Comunidad

Únete a la comunidad de Slack de MCParty para conectarte con otros entusiastas de MCP, hacer preguntas y compartir tus experiencias con FastAPI-MCP.

Requisitos

  • Python 3.10+ (Recomendado 3.12)
  • uv

Licencia

Licencia MIT. Copyright (c) 2024 Tadata Inc.