proxy mcp-openapi

mcp-openapi-proxy es un paquete de Python que implementa un servidor de Protocolo de Contexto de Modelo (MCP), diseñado para exponer dinámicamente las API REST (definidas por las especificaciones de OpenAPI) como herramientas MCP. Esto facilita la integración fluida de las API descritas por OpenAPI en flujos de trabajo basados en MCP.

Tabla de contenido

• Descripción general
• Características
• Instalación
  • Integración del ecosistema MCP
• Modos de operación
  • Modo FastMCP (modo simple)
  • Modo de bajo nivel (predeterminado)
• Variables de entorno
• Ejemplos
  • Ejemplo de Glama
  • Ejemplo de Fly.io
  • Ejemplo de renderizado
  • Ejemplo de holgura
  • Ejemplo de GetZep
  • Ejemplo de Virustotal
  • Ejemplo de noción
  • Ejemplo de asana
  • Ejemplo de APIs.guru
  • Ejemplo de NetBox
  • Ejemplo de API de Box
  • Ejemplo de API de WolframAlpha
• Solución de problemas
• Licencia

Descripción general

El paquete ofrece dos modos operativos:

• Modo de bajo nivel (predeterminado): registra dinámicamente las herramientas correspondientes a todos los puntos finales de API válidos especificados en un documento OpenAPI (por ejemplo, /chat/completions se convierte en chat_completions() ).
• Modo FastMCP (modo simple): proporciona un enfoque optimizado al exponer un conjunto predefinido de herramientas (por ejemplo, list_functions() y call_function() ) basadas en configuraciones estáticas.

Características

• Generación dinámica de herramientas: crea automáticamente herramientas MCP a partir de definiciones de puntos finales de OpenAPI.
• Opción de modo simple: ofrece una alternativa de configuración estática a través del modo FastMCP.
• Compatibilidad con la especificación OpenAPI: compatible con OpenAPI v3 con posible compatibilidad con v2.
• Filtrado flexible: permite el filtrado de puntos finales a través de listas blancas por rutas u otros criterios.
• Autenticación de carga útil: admite autenticación personalizada a través de expresiones JMESPath (por ejemplo, para API como Slack que esperan tokens en la carga útil, no en el encabezado HTTP).
• Autenticación de encabezado: utiliza Bearer de manera predeterminada para API_KEY en el encabezado de autorización, personalizable para API como Fly.io que requieren Api-Key .
• Integración con MCP: se integra perfectamente con los ecosistemas de MCP para invocar API REST como herramientas.

Instalación

Instale el paquete directamente desde PyPI usando el siguiente comando:

Integración del ecosistema MCP

Para incorporar mcp-openapi-proxy a su ecosistema MCP, configúrelo en la configuración de mcpServers . A continuación, se muestra un ejemplo genérico:

Consulte la sección Ejemplos a continuación para obtener configuraciones prácticas adaptadas a API específicas.

Modos de operación

Modo FastMCP (modo simple)

• Habilitado por: Establecer la variable de entorno OPENAPI_SIMPLE_MODE=true .
• Descripción: Expone un conjunto fijo de herramientas derivadas de puntos finales OpenAPI específicos según se define en el código.
• Configuración: se basa en variables de entorno para especificar el comportamiento de la herramienta.

Modo de bajo nivel (predeterminado)

• Descripción: Registra automáticamente todos los puntos finales de API válidos de la especificación OpenAPI proporcionada como herramientas individuales.
• Nomenclatura de herramientas: deriva los nombres de las herramientas de las rutas y métodos de OpenAPI normalizados.
• Comportamiento: genera descripciones de herramientas a partir de resúmenes y descripciones de operaciones de OpenAPI.

Variables de entorno

• OPENAPI_SPEC_URL : (obligatorio) La URL del archivo JSON de especificación OpenAPI (por ejemplo, https://example.com/spec.json o file:///path/to/local/spec.json ).
• OPENAPI_LOGFILE_PATH : (opcional) especifica la ruta del archivo de registro.
• OPENAPI_SIMPLE_MODE : (opcional) Establezca en true para habilitar el modo FastMCP.
• TOOL_WHITELIST : (opcional) una lista separada por comas de rutas de puntos finales para exponer como herramientas.
• TOOL_NAME_PREFIX : (opcional) Un prefijo para agregar a todos los nombres de herramientas.
• API_KEY : (opcional) Token de autenticación para la API enviado como Bearer <API_KEY> en el encabezado de autorización de forma predeterminada.
• API_AUTH_TYPE : (opcional) anula el tipo de encabezado de autorización Bearer predeterminado (por ejemplo, Api-Key para GetZep).
• STRIP_PARAM : (opcional) expresión JMESPath para eliminar parámetros no deseados (por ejemplo, token para Slack).
• DEBUG : (opcional) habilita el registro de depuración detallado cuando se establece en "verdadero", "1" o "sí".
• EXTRA_HEADERS : (opcional) encabezados HTTP adicionales en formato "Encabezado: Valor" (uno por línea) para adjuntar a las solicitudes de API salientes.
• SERVER_URL_OVERRIDE : (opcional) anula la URL base de la especificación OpenAPI cuando se configura, útil para implementaciones personalizadas.
• TOOL_NAME_MAX_LENGTH : (opcional) Trunca los nombres de herramientas a una longitud máxima.
• Variable adicional: OPENAPI_SPEC_URL_<hash> – una variante para configuraciones únicas por prueba (recurre a OPENAPI_SPEC_URL ).
• IGNORE_SSL_SPEC : (opcional) Establezca como true para deshabilitar la verificación del certificado SSL al obtener la especificación OpenAPI.
• IGNORE_SSL_TOOLS : (opcional) Establezca como true para deshabilitar la verificación del certificado SSL para las solicitudes de API realizadas por herramientas.

Ejemplos

Para realizar pruebas, puede ejecutar el comando uvx como se muestra en los ejemplos y luego interactuar con el servidor MCP mediante mensajes JSON-RPC para listar herramientas y recursos. Consulte la sección "Pruebas JSON-RPC" a continuación.

Ejemplo de Glama

Glama ofrece la configuración mínima para mcp-openapi-proxy, que solo requiere la variable de entorno OPENAPI_SPEC_URL . Esta simplicidad la hace ideal para pruebas rápidas.

1. Verificar la especificación de OpenAPI

Recupere la especificación Glama OpenAPI:

Asegúrese de que la respuesta sea un documento JSON OpenAPI válido.

2. Configurar mcp-openapi-proxy para Glama

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

3. Pruebas

Inicie el servicio con:

Luego consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de Fly.io

Fly.io ofrece una API sencilla para gestionar máquinas, lo que la convierte en un punto de partida ideal. Obtenga un token de API en la documentación de Fly.io.

1. Verificar la especificación de OpenAPI

Recupere la especificación OpenAPI de Fly.io:

Asegúrese de que la respuesta sea un documento JSON OpenAPI válido.

2. Configurar mcp-openapi-proxy para Fly.io

Actualice la configuración de su ecosistema MCP:

• OPENAPI_SPEC_URL : Apunta a la especificación OpenAPI de Fly.io.
• API_KEY : Su token de API de Fly.io (reemplace <your_flyio_token_here> ).
• API_AUTH_TYPE : Establezca en Api-Key para la autenticación basada en encabezado de Fly.io (anula Bearer predeterminado).

3. Pruebas

Después de iniciar el servicio, consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de renderizado

Render ofrece alojamiento de infraestructura que se puede gestionar mediante una API. El archivo de configuración examples/render-claude_desktop_config.json muestra cómo configurar rápidamente su ecosistema MCP con una configuración mínima.

1. Verificar la especificación de OpenAPI

Recupere la especificación Render OpenAPI:

Asegúrese de que la respuesta sea un documento OpenAPI válido.

2. Configurar mcp-openapi-proxy para Render

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

3. Pruebas

Inicie el proxy con su configuración de Render:

Luego consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de holgura

La API de Slack muestra cómo eliminar la carga útil de tokens innecesaria mediante JMESPath. Obtén un token de bot en la documentación de la API de Slack .

1. Verificar la especificación de OpenAPI

Recupere la especificación OpenAPI de Slack:

Asegúrese de que sea un documento JSON OpenAPI válido.

2. Configurar mcp-openapi-proxy para Slack

Actualice su configuración:

• OPENAPI_SPEC_URL : URL de la especificación OpenAPI de Slack.
• TOOL_WHITELIST : limita las herramientas a grupos de puntos finales útiles (por ejemplo, chat, conversaciones, usuarios).
• API_KEY : tu token de bot de Slack (por ejemplo, xoxb-... , reemplaza <your_slack_bot_token> ).
• STRIP_PARAM : elimina el campo de token de la carga útil de la solicitud.
• TOOL_NAME_PREFIX : Antepone slack_ a los nombres de las herramientas.

3. Pruebas

Después de iniciar el servicio, consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de GetZep

GetZep ofrece una API en la nube gratuita para la gestión de memoria con endpoints detallados. Dado que GetZep no proporcionó una especificación oficial de OpenAPI, este proyecto incluye una especificación generada alojada en GitHub para mayor comodidad. Los usuarios pueden generar especificaciones de OpenAPI para cualquier API REST y referenciarlas localmente (por ejemplo, file:///path/to/spec.json ). Obtenga una clave de API en la documentación de GetZep .

1. Verificar la especificación de OpenAPI

Recupere la especificación GetZep OpenAPI proporcionada por el proyecto:

Asegúrate de que sea un documento JSON de OpenAPI válido. Como alternativa, genera tu propia especificación y usa una URL file:// para referenciar un archivo local.

2. Configurar mcp-openapi-proxy para GetZep

Actualice su configuración:

• OPENAPI_SPEC_URL : apunta a la especificación GetZep Swagger proporcionada por el proyecto (o use file:///path/to/your/spec.json para un archivo local).
• TOOL_WHITELIST : Límites a los puntos finales de /sessions .
• API_KEY : Su clave API de GetZep.
• API_AUTH_TYPE : utiliza Api-Key para autenticación basada en encabezado.
• TOOL_NAME_PREFIX : Antepone zep_ a los nombres de las herramientas.

3. Pruebas

Después de iniciar el servicio, consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de Virustotal

Este ejemplo demuestra:

• Uso de un archivo de especificación YAML OpenAPI
• Uso del encabezado de autenticación HTTP personalizado "x-apikey"

1. Verificar la especificación de OpenAPI

Recupere la especificación OpenAPI de Virustotal:

Asegúrese de que la respuesta sea un documento YAML OpenAPI válido.

2. Configurar mcp-openapi-proxy para Virustotal

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

Puntos clave de configuración:

• De forma predeterminada, el proxy espera una especificación JSON y envía la clave API con un prefijo Bearer.
• Para utilizar una especificación OpenAPI YAML, incluya OPENAPI_SPEC_FORMAT="yaml" .
• Nota: VirusTotal requiere un encabezado de autenticación especial; EXTRA_HEADERS se utiliza para transmitir la clave API como "x-apikey: ${VIRUSTOTAL_API_KEY}".

3. Pruebas

Inicie el proxy con la configuración de Virustotal:

Después de iniciar el servicio, consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de noción

La API de Notion requiere la especificación de una versión específica mediante encabezados HTTP. Este ejemplo utiliza la variable de entorno EXTRA_HEADERS para incluir el encabezado requerido y se centra en la verificación de la especificación de OpenAPI.

1. Verificar la especificación de OpenAPI

Recupere la especificación Notion OpenAPI:

Asegúrese de que la respuesta sea un documento YAML válido.

2. Configurar mcp-openapi-proxy para Notion

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

3. Pruebas

Inicie el proxy con la configuración de Notion:

Después de iniciar el servicio, consulte la sección Pruebas JSON-RPC para obtener instrucciones sobre cómo enumerar recursos y herramientas.

Ejemplo de asana

Asana ofrece un amplio conjunto de puntos de conexión para gestionar espacios de trabajo, tareas, proyectos y usuarios. Las pruebas de integración demuestran el uso de puntos de conexión como GET /workspaces , GET /tasks y GET /projects .

1. Verificar la especificación de OpenAPI

Recupere la especificación de Asana OpenAPI:

Asegúrese de que la respuesta sea un documento YAML (o JSON) válido.

2. Configurar mcp-openapi-proxy para Asana

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

Nota: La mayoría de los puntos finales de la API de Asana requieren autenticación. Configure ASANA_API_KEY en su entorno o archivo .env con un token válido.

3. Pruebas

Inicie el servicio con:

Luego puede utilizar el ecosistema MCP para enumerar e invocar herramientas para puntos finales como /dcim/devices/ y /ipam/ip-addresses/ .

Ejemplo de APIs.guru

APIs.guru proporciona un directorio de definiciones de OpenAPI para miles de API públicas. Este ejemplo muestra cómo usar mcp-openapi-proxy para exponer el directorio APIs.guru como herramientas MCP.

1. Verificar la especificación de OpenAPI

Recupere la especificación OpenAPI de APIs.guru:

Asegúrese de que la respuesta sea un documento YAML OpenAPI válido.

2. Configurar mcp-openapi-proxy para APIs.guru

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

3. Pruebas

Inicie el servicio con:

Luego puede utilizar el ecosistema MCP para enumerar e invocar herramientas como listAPIs , getMetrics y getProviders que están definidas en el directorio APIs.guru.

Ejemplo de NetBox

NetBox es una herramienta de código abierto para la gestión de direcciones IP (IPAM) y la gestión de infraestructura de centros de datos (DCIM). Este ejemplo muestra cómo usar mcp-openapi-proxy para exponer la API de NetBox como herramientas MCP.

1. Verificar la especificación de OpenAPI

Recupere la especificación NetBox OpenAPI:

Asegúrese de que la respuesta sea un documento YAML OpenAPI válido.

2. Configurar mcp-openapi-proxy para NetBox

Agregue la siguiente configuración a la configuración de su ecosistema MCP:

Nota: La mayoría de los puntos finales de la API de NetBox requieren autenticación. Configure NETBOX_API_KEY en su entorno o archivo .env con un token válido.

3. Pruebas

Inicie el servicio con:

Luego puede utilizar el ecosistema MCP para enumerar e invocar herramientas para puntos finales como /dcim/devices/ y /ipam/ip-addresses/ .

Ejemplo de API de Box

Puedes integrar la API de Box Platform con tu propio token de desarrollador para acceder autenticado a tu cuenta de Box. Este ejemplo muestra cómo exponer los puntos finales de la API de Box como herramientas MCP.

Ejemplo de configuración: examples/box-claude_desktop_config.json

• Establezca su token de desarrollador de Box como una variable de entorno en .env :
  BOX_API_KEY=your_box_developer_token
• O ejecute el proxy con una sola línea:
  OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml" API_KEY="$BOX_API_KEY" uvx mcp-openapi-proxy

Ahora puede usar el ecosistema MCP para listar e invocar las herramientas de la API de Box. Para pruebas de integración, consulte tests/integration/test_box_integration.py .

Ejemplo de API de WolframAlpha

Puedes integrar la API de WolframAlpha usando tu propio ID de aplicación para obtener acceso autenticado. Este ejemplo muestra cómo exponer los endpoints de la API de WolframAlpha como herramientas MCP.

Ejemplo de configuración: examples/wolframalpha-claude_desktop_config.json

• Establezca su ID de aplicación WolframAlpha como una variable de entorno en .env :
  WOLFRAM_LLM_APP_ID=your_wolfram_app_id
• O ejecute el proxy con una sola línea:
  OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml" API_KEY="$WOLFRAM_LLM_APP_ID" uvx mcp-openapi-proxy

Ahora puede usar el ecosistema MCP para listar e invocar las herramientas de la API de WolframAlpha. Para pruebas de integración, consulte tests/integration/test_wolframalpha_integration.py .

Solución de problemas

Pruebas JSON-RPC

Para realizar pruebas alternativas, puede interactuar con el servidor MCP mediante JSON-RPC. Tras iniciar el servidor, pegue el siguiente mensaje de inicialización:

Respuesta esperada:

A continuación pegue estos mensajes de seguimiento:

• OPENAPI_SPEC_URL faltante: asegúrese de que esté configurado en una URL JSON de OpenAPI válida o una ruta de archivo local.
• Especificación no válida: verifique que el documento OpenAPI cumpla con el estándar.
• Problemas de filtrado de herramientas: comprobar que TOOL_WHITELIST coincida con los puntos finales deseados.
• Errores de autenticación: confirme que API_KEY y API_AUTH_TYPE sean correctos.
• Registro: establezca DEBUG=true para obtener una salida detallada en stderr.
• Servidor de prueba: Ejecutar directamente:

Licencia

Licencia MIT