mcp-openapi-runner

Convierte cualquier especificación OpenAPI en herramientas MCP invocables para Claude: apunta a cualquier especificación OpenAPI 3.x y Claude puede llamar a cada endpoint mediante lenguaje natural.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-openapi

Convierte cualquier especificación OpenAPI en herramientas MCP para Claude — cero configuración, acceso instantáneo a la API.

Apunta mcp-openapi-runner a cualquier especificación OpenAPI 3.x y Claude podrá llamar a cada endpoint mediante lenguaje natural. Sin código de integración personalizado. Sin definiciones manuales de herramientas. Una línea de configuración.

¿Por qué mcp-openapi?

Sin mcp-openapi	Con mcp-openapi
Escribir un servidor MCP personalizado por API	Una línea de configuración por API
Definir esquemas de herramientas manualmente	Generados automáticamente desde la especificación OpenAPI
Manejar autenticación, parámetros y cuerpo manualmente	Autenticación integrada + manejo de parámetros
Mantener el código a medida que la API evoluciona	Cambios en la especificación = herramientas actualizadas automáticamente

Inicio rápido

Añade a tu configuración MCP de Claude Desktop / Claude Code / Cursor / Cline:

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

Eso es todo. Claude ahora puede descubrir y llamar a cada endpoint de esa API.

Ejemplo de conversación

Tú: ¿Qué mascotas hay disponibles? Añade un nuevo perro llamado Buddy.

Claude: Déjame ver qué hay disponible. [llama a list_endpoints → descubre findPetsByStatus, addPet, ...] [llama a call_endpoint → findPetsByStatus con status=available]

Hay 3 mascotas disponibles actualmente. Ahora añadiré a Buddy... [llama a call_endpoint → addPet con {"name":"Buddy","status":"available"}]

¡Listo! Buddy ha sido añadido con el ID 12345.

Características

Cero configuración — solo apunta a una URL o archivo de especificación
Cualquier especificación OpenAPI 3.x — JSON o YAML, local o remota, $ref resuelto automáticamente
operationIds generados automáticamente — funciona incluso cuando la especificación no los define
Autenticación integrada — Bearer, API key, autenticación Basic mediante variables de entorno
Filtrado de endpoints — expón solo los endpoints que necesitas con --filter
Cabeceras personalizadas — pasa cabeceras arbitrarias con --header
Anulación de URL del servidor — apunta a staging/local con --server-url
Diseño de dos herramientas — flujo de trabajo simple list_endpoints → call_endpoint
Funciona en todas partes — Claude Desktop, Claude Code, Cursor, Cline, cualquier cliente MCP

Configuraciones listas para usar

Stripe

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "sk_test_..."
      }
    }
  }
}

GitHub REST API

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--filter", "repos"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "ghp_..."
      }
    }
  }
}

Tu API interna

{
  "mcpServers": {
    "internal": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "http://localhost:8080/openapi.json"],
      "env": {
        "OPENAPI_API_KEY": "dev-key-123"
      }
    }
  }
}

Jira (Atlassian)

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner",
        "--spec", "https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json",
        "--server-url", "https://your-domain.atlassian.net",
        "--filter", "issue"],
      "env": {
        "OPENAPI_BASIC_USER": "you@company.com",
        "OPENAPI_BASIC_PASS": "your-api-token"
      }
    }
  }
}

Autenticación

Pasa credenciales mediante variables de entorno:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://api.example.com/openapi.json"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Variable	Descripción
`OPENAPI_BEARER_TOKEN`	Token Bearer → `Authorization: Bearer <token>`
`OPENAPI_API_KEY`	Valor de la API key
`OPENAPI_API_KEY_HEADER`	Nombre de la cabecera para la API key (por defecto: `X-Api-Key`)
`OPENAPI_BASIC_USER`	Nombre de usuario para autenticación HTTP Basic
`OPENAPI_BASIC_PASS`	Contraseña para autenticación HTTP Basic

Opciones de CLI

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

Options:
  --spec         Path or URL to an OpenAPI 3.x spec (JSON or YAML)
  --server-url   Override the base URL from the spec
  --filter       Only expose endpoints matching a pattern (path, tag, or operationId)
  --header       Add custom header to all requests ("Name: Value", repeatable)
  --help         Show help

Ejemplos

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

# Only pet-related endpoints
npx mcp-openapi-runner --spec ./openapi.yaml --filter pets

# Point at local dev server
npx mcp-openapi-runner --spec ./openapi.yaml --server-url http://localhost:3000

# Custom headers
npx mcp-openapi-runner --spec ./openapi.yaml --header "X-Tenant: acme" --header "X-Debug: true"

# With auth
OPENAPI_BEARER_TOKEN=mytoken npx mcp-openapi-runner --spec https://api.example.com/openapi.json

Herramientas

mcp-openapi-runner expone exactamente dos herramientas:

Herramienta	Descripción
`list_endpoints`	Devuelve todas las operaciones agrupadas por etiqueta con operationIds, métodos, rutas y parámetros
`call_endpoint`	Ejecuta cualquier operación mediante `operationId` con parámetros de ruta/consulta/cabecera/cuerpo

El diseño de dos herramientas significa que Claude siempre tiene un flujo de trabajo claro: descubrir → llamar.

Cómo funciona

Carga la especificación OpenAPI desde la URL o ruta de archivo dada
Desreferencia todos los esquemas $ref usando @apidevtools/swagger-parser
Aplica el filtro de endpoints si --filter está configurado
Registra dos herramientas MCP con el cliente conectado
list_endpoints genera un resumen legible para humanos y LLM de todas las operaciones
call_endpoint resuelve parámetros, construye la URL, adjunta autenticación + cabeceras personalizadas, y devuelve la respuesta

Requisitos

Node.js 18+
Especificación OpenAPI 3.x (JSON o YAML, archivo local o URL)

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para las pautas.

Licencia

MIT