mcp-openapi

Convierte cualquier especificación OpenAPI/Swagger en herramientas de Claude. Sin configuración, sin código.

Documentación

mcp-openapi

Convierte cualquier especificación OpenAPI/Swagger en herramientas MCP — para que Claude y otros asistentes de IA puedan llamar a tus APIs REST.

Apunta mcp-openapi a cualquier URL de especificación OpenAPI 3.x o Swagger 2.0 y generará herramientas de Model Context Protocol (MCP) automáticamente. Sin generación de código, sin archivos de configuración, sin código repetitivo. Tu asistente de IA obtiene herramientas invocables para cada endpoint de API en segundos.

Inicio Rápido

1. Ejecútalo (sin necesidad de instalación):

npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

2. Agrégalo a Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

3. Pídele a Claude que lo use:

"Lista todas las mascotas disponibles en la tienda"

Claude ve herramientas MCP como find_pets_by_status, get_pet_by_id, add_pet y las llama directamente.

¿Por qué mcp-openapi?

La mayoría de los puentes MCP-a-API requieren que escribas definiciones de herramientas manualmente o que generes código a partir de una especificación. mcp-openapi omite todo eso.

Característica	mcp-openapi	Servidores MCP escritos a mano	Herramientas HTTP genéricas
Configuración cero	Sí	No	Parcial
OpenAPI 3.x + Swagger 2.0	Sí	N/A	N/A
Esquemas de parámetros planos (optimizados para LLM)	Sí	Manual	No
Nombres inteligentes de herramientas desde operationId	Sí	Manual	No
Autenticación (API key, Bearer, OAuth2)	Integrada	Hecho a mano	Hecho a mano
Reintentos con retroceso exponencial	Integrado	Hecho a mano	Hecho a mano
Truncamiento de respuestas para contexto LLM	Integrado	Hecho a mano	No

Los esquemas de parámetros planos son el diferenciador clave. En lugar de pasar objetos JSON anidados (que los LLM frecuentemente manejan mal), mcp-openapi aplana los parámetros de ruta, consulta, cabecera y cuerpo en un único objeto plano. Esto mejora drásticamente la precisión de las llamadas a herramientas.

Cómo Funciona

OpenAPI/Swagger Spec          mcp-openapi               AI Assistant
     (URL or file)                                      (Claude, etc.)
          |                         |                         |
          |   1. Parse & validate   |                         |
          |------------------------>|                         |
          |                         |                         |
          |   2. Generate MCP tools |                         |
          |   (one per endpoint)    |                         |
          |------------------------>|                         |
          |                         |                         |
          |                         |   3. Register tools     |
          |                         |   via stdio transport   |
          |                         |------------------------>|
          |                         |                         |
          |                         |   4. AI calls a tool    |
          |                         |<------------------------|
          |                         |                         |
          |   5. Build & execute    |                         |
          |   HTTP request          |                         |
          |<------------------------|                         |
          |                         |                         |
          |   6. Return truncated   |                         |
          |   response to AI        |                         |
          |------------------------>|------------------------>|

Cada endpoint de API se convierte en una herramienta MCP:

El nombre de la herramienta se deriva de operationId (convertido a snake_case) o de method + path
Los parámetros se aplanan en un único esquema de entrada (parámetros de ruta, consulta, cabecera y cuerpo combinados)
Las respuestas se truncan a ~50KB para mantenerse dentro de los límites de contexto del LLM
Los errores (429, 5xx) activan reintentos automáticos con retroceso exponencial (hasta 3 reintentos)

Integración con Claude Desktop

Añade cualquier API a Claude Desktop editando tu archivo de configuración:

Ubicación:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

API pública (sin autenticación)

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"
      ]
    }
  }
}

API con Bearer Token

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--auth-type", "bearer",
        "--auth-token", "$GITHUB_TOKEN",
        "--prefix", "github",
        "--include", "listReposForAuthenticatedUser,getRepo,listIssues,createIssue"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

API con API Key

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "mcp-openapi",
        "--spec", "https://api.weather.example.com/openapi.json",
        "--auth-type", "api-key",
        "--auth-name", "X-API-Key",
        "--auth-value", "$WEATHER_API_KEY",
        "--auth-in", "header"
      ],
      "env": {
        "WEATHER_API_KEY": "your_key_here"
      }
    }
  }
}

Referencia de CLI

npx mcp-openapi --spec <url-or-path> [options]

Opciones Generales

Opción	Corta	Predeterminado	Descripción
`--spec <url\|path>`	`-s`	obligatorio	URL de especificación OpenAPI o ruta de archivo local
`--config <path>`	`-c`		Ruta de archivo de configuración JSON
`--base-url <url>`		desde la especificación	Sobrescribir la URL base de la API
`--prefix <name>`			Prefijo para todos los nombres de herramientas (ej. `github` -> `github_list_repos`)
`--include <patterns>`		todos	operationIds separados por comas para incluir
`--exclude <patterns>`		ninguno	operationIds separados por comas para excluir
`--timeout <ms>`		`30000`	Tiempo de espera de solicitud HTTP en milisegundos
`--max-retries <n>`		`3`	Máximo de reintentos en respuestas 429/5xx
`--header <name:value>`	`-H`		Cabecera personalizada (repetible)
`--transport <type>`		`stdio`	Tipo de transporte: `stdio` o `sse`
`--port <n>`		`3000`	Puerto para transporte SSE
`--help`	`-h`		Mostrar ayuda
`--version`	`-v`		Mostrar versión
`--license-key <key>`			Clave de licencia Pro (o variable de entorno `$MCP_OPENAPI_LICENSE_KEY`)
`--server <selector>`		`0`	Seleccionar servidor API por índice, URL parcial o URL exacta
`--no-doc-warnings`			Suprimir advertencias de calidad de documentación al inicio
`--dynamic-discovery`		auto (100+)	Habilitar descubrimiento dinámico de herramientas para APIs grandes

Opciones de Autenticación

Token Bearer:

Opción	Descripción
`--auth-type bearer`	Usar autenticación con token Bearer
`--auth-token <token>`	El valor del token (soporta sintaxis `$ENV_VAR`)

API key:

Opción	Descripción
`--auth-type api-key`	Usar autenticación con API key
`--auth-name <name>`	Nombre del parámetro de cabecera o consulta
`--auth-value <value>`	El valor de la API key (soporta sintaxis `$ENV_VAR`)
`--auth-in <header\|query>`	Dónde enviar la clave (predeterminado: `header`)

Credenciales de cliente OAuth2:

Opción	Descripción
`--auth-type oauth2`	Usar flujo de credenciales de cliente OAuth2
`--auth-client-id <id>`	ID de cliente OAuth2
`--auth-client-secret <secret>`	Secreto de cliente OAuth2
`--auth-token-url <url>`	URL del endpoint de token
`--auth-scopes <scopes>`	Ámbitos separados por comas

Ejemplos de CLI

# Basic usage with a remote spec
npx mcp-openapi --spec https://petstore3.swagger.io/api/v3/openapi.json

# Local YAML spec with Bearer auth
npx mcp-openapi --spec ./api.yaml --auth-type bearer --auth-token '$API_KEY'

# Filter to specific endpoints with a prefix
npx mcp-openapi --spec ./api.json --prefix myapi --include 'listUsers,getUser'

# Override base URL (useful for local dev)
npx mcp-openapi --spec https://api.example.com/openapi.json --base-url http://localhost:3000

# Add custom headers
npx mcp-openapi --spec ./api.json -H 'X-Custom: value' -H 'X-Another: value2'

# Use a JSON config file
npx mcp-openapi --config ./mcp-config.json

# Select staging server
npx mcp-openapi --spec ./api.json --server staging

# Large API with dynamic discovery
npx mcp-openapi --spec https://api.stripe.com/openapi.json --dynamic-discovery

Formato de Archivo de Configuración

En lugar de banderas de CLI, puedes usar un archivo de configuración JSON:

{
  "spec": "https://api.example.com/openapi.json",
  "prefix": "myapi",
  "include": ["listUsers", "getUser", "createUser"],
  "auth": {
    "type": "bearer",
    "token": "$API_TOKEN"
  },
  "timeout": 15000,
  "maxRetries": 2,
  "headers": {
    "X-Custom-Header": "value"
  }
}

Los argumentos de CLI tienen prioridad sobre los valores del archivo de configuración.

Especificaciones Soportadas

Formato	Versiones	Tipos de archivo
OpenAPI	3.0.x, 3.1.x	`.json`, `.yaml`, `.yml`
Swagger	2.0	`.json`, `.yaml`, `.yml`

Las especificaciones se pueden cargar desde:

URLs remotas (https://...)
Rutas de archivo local (./api.yaml, /absolute/path/spec.json)

Características de v0.3.0

Advertencias de Calidad de Documentación

Al inicio, mcp-openapi verifica la calidad de la documentación de cada herramienta. Si los endpoints tienen descripciones escasas (menos de 50 caracteres), verás una advertencia:

[mcp-openapi] WARN: Doc quality: 11 of 47 tools have sparse documentation (<50 chars)
[mcp-openapi] WARN:   Affected: getUser, createOrder, deleteItem, updateCart, listTags, ...
[mcp-openapi] WARN:   LLM accuracy may be reduced for these endpoints.

Esto te ayuda a identificar qué endpoints de API podrían causar baja precisión en las llamadas de herramientas del LLM. Suprime con --no-doc-warnings.

Filtrado de Servidores

Las especificaciones OpenAPI pueden definir múltiples servidores (producción, staging, desarrollo). Selecciona cuál usar:

# Use first server (default behavior)
mcp-openapi --spec api.json --server 0

# Match by URL keyword
mcp-openapi --spec api.json --server prod

# Exact URL
mcp-openapi --spec api.json --server https://api.example.com/v2

Si el selector no coincide, verás todos los servidores disponibles listados.

Descubrimiento Dinámico de Herramientas

Para APIs grandes con 100+ endpoints, registrar todas las herramientas a la vez puede abrumar el contexto del LLM. El descubrimiento dinámico resuelve esto registrando 3 meta-herramientas en su lugar:

Meta-herramienta	Descripción
`search_operations(query)`	Buscar herramientas por palabra clave en nombres, descripciones y etiquetas
`list_by_tag(tag?)`	Explorar herramientas por etiqueta OpenAPI, o listar todas las etiquetas
`get_tool_details(tool_name)`	Obtener el esquema de parámetros completo para una herramienta específica

El LLM explora la API a través de estas meta-herramientas, luego llama a endpoints específicos por nombre.

# Explicit opt-in
mcp-openapi --spec large-api.json --dynamic-discovery

# Auto-enabled when spec has 100+ endpoints
mcp-openapi --spec https://api.github.com/openapi.json

O mediante archivo de configuración:

{
  "spec": "https://api.stripe.com/openapi.json",
  "dynamicDiscovery": true,
  "auth": { "type": "bearer", "token": "$STRIPE_KEY" }
}

Características Pro (v0.2.0+)

mcp-openapi incluye características Pro opcionales para equipos y usuarios avanzados, controladas por una clave de licencia.

Transformaciones Personalizadas de Respuestas

Da forma a las respuestas de API con expresiones JMESPath antes de que lleguen al LLM — reduciendo el uso de tokens y mejorando la precisión:

{
  "spec": "https://api.github.com/openapi.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "transforms": {
    "list_repos": "data[].{name: name, stars: stargazers_count, url: html_url}",
    "list_*": "data[].{id: id, name: name}"
  }
}

Manejo Inteligente de Respuestas

En lugar de truncar duramente las respuestas grandes a 50KB, Pro habilita el truncamiento inteligente:

División de arrays: Los arrays grandes muestran los primeros N elementos + metadatos ("showing 10 of 847 items")
Poda de profundidad: Los objetos anidados profundos se resumen más allá de una profundidad configurable
Preservación de estructura: Siempre ves la forma de los datos, nunca un corte a mitad de JSON

{
  "spec": "./api.json",
  "licenseKey": "$MCP_OPENAPI_LICENSE_KEY",
  "response": {
    "maxLength": 50000,
    "arraySliceSize": 10,
    "maxDepth": 4
  }
}

Próximamente

Composición Multi-API — Cargar múltiples especificaciones OpenAPI en una sesión MCP
Analíticas de Uso — Rastrear llamadas a herramientas, latencia y tasas de error

¿Interesado en Pro? Marca el repositorio con una estrella y abre un issue para obtener acceso temprano.

Uso Programático

También puedes usar mcp-openapi como biblioteca en tu propio servidor MCP:

import { createServer } from 'mcp-openapi';

const { server, tools, spec } = await createServer({
  spec: 'https://petstore3.swagger.io/api/v3/openapi.json',
  prefix: 'petstore',
  auth: {
    type: 'bearer',
    token: process.env.API_TOKEN,
  },
});

console.log(`Loaded ${tools.length} tools from ${spec.info.title}`);

Requisitos

Node.js 18 o posterior
Una especificación OpenAPI 3.x o Swagger 2.0 (URL o archivo local)

Contribuciones

Las contribuciones son bienvenidas. Así es como empezar:

git clone https://github.com/Docat0209/mcp-openapi.git
cd mcp-openapi
pnpm install
pnpm test
pnpm build

Antes de enviar un PR:

Añade pruebas para nuevas características
Ejecuta pnpm lint y corrige cualquier problema
Sigue Conventional Commits para los mensajes de commit

Relacionados

graphql-to-mcp — El mismo enfoque de configuración cero para APIs GraphQL

Licencia

MIT

Palabras clave

mcp, model-context-protocol, openapi, swagger, claude, ai, llm, api, tools, rest-api, ai-tools, mcp-server