OpenAPI to MCP Server

Una herramienta para crear servidores MCP a partir de especificaciones OpenAPI/Swagger, permitiendo que asistentes de IA interactúen con tus APIs.

GitHub
47
Prueba este MCPPatrocinado

Documentación

OpenAPI to MCP Server

Una herramienta que crea servidores MCP (Model Context Protocol) a partir de especificaciones OpenAPI/Swagger, permitiendo que los asistentes de IA interactúen con tus APIs. Crea tus propios MCP personalizados y con tu marca para APIs o servicios específicos.

Descripción general

Este proyecto crea un servidor MCP dinámico que transforma especificaciones OpenAPI en herramientas MCP. Permite la integración fluida de APIs REST con asistentes de IA mediante el Protocolo de Contexto de Modelo (Model Context Protocol), convirtiendo cualquier API en una herramienta accesible para IA.

Características

  • Carga dinámica de especificaciones OpenAPI desde archivos o URLs HTTP/HTTPS
  • Soporte para OpenAPI Overlays cargados desde archivos o URLs HTTP/HTTPS
  • Mapeo personalizable de operaciones OpenAPI a herramientas MCP
  • Filtrado avanzado de operaciones mediante patrones glob tanto para operationId como para rutas URL
  • Manejo integral de parámetros con preservación de formato y metadatos de ubicación
  • Manejo de autenticación de API
  • Metadatos de OpenAPI (título, versión, descripción) utilizados para configurar el servidor MCP
  • Descripciones jerárquicas de respaldo (descripción de operación → resumen de operación → resumen de ruta)
  • Soporte de cabeceras HTTP personalizadas mediante variables de entorno y CLI
  • Cabecera X-MCP para seguimiento e identificación de solicitudes de API
  • Soporte para extensiones personalizadas x-mcp a nivel de ruta para sobrescribir nombres y descripciones de herramientas

Uso con Asistentes de IA

Esta herramienta crea un servidor MCP que permite a los asistentes de IA interactuar con APIs definidas por especificaciones OpenAPI. La forma principal de usarla es configurando tu asistente de IA para que la ejecute directamente como una herramienta MCP.

Configuración en Claude Desktop

  1. Asegúrate de tener Node.js instalado en tu computadora

  2. Abre Claude Desktop y navega a Configuración > Desarrollador

  3. Edita el archivo de configuración (o se creará si no existe):

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

  4. Añade esta configuración (personalízala según sea necesario):

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}
  1. Reinicia Claude Desktop
  2. Ahora deberías ver un icono de martillo en el cuadro de entrada del chat. Haz clic en él para acceder a tus herramientas de API.

Personalización de la Configuración

Puedes ajustar el array args para personalizar tu servidor MCP con varias opciones:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--spec",
        "./path/to/your/openapi.json",
        "--overlays",
        "./path/to/overlay.json,https://example.com/api/overlay.json",
        "--whitelist",
        "getPet*,POST:/users/*",
        "--targetUrl",
        "https://api.example.com"
      ],
      "enabled": true
    }
  }
}

Configuración en Cursor

  1. Crea un archivo de configuración en una de estas ubicaciones:

    • Específico del proyecto: .cursor/mcp.json en el directorio de tu proyecto
    • Global: ~/.cursor/mcp.json en tu directorio de inicio

  2. Añade esta configuración (ajústala según sea necesario para tu API):

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}
  1. Reinicia Cursor o recarga la ventana

Uso con Vercel AI SDK

También puedes usar este servidor MCP directamente en tus aplicaciones JavaScript/TypeScript utilizando el cliente MCP del Vercel AI SDK:

import { experimental_createMCPClient } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
import { generateText } from 'ai';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

// Initialize the Google Generative AI provider
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY, // Set your API key in environment variables
});
const model = google('gemini-2.0-flash');

// Create an MCP client with stdio transport
const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'stdio',
    command: 'npx', // Command to run the MCP server
    args: ['-y', '@tyk-technologies/api-to-mcp', '--spec', 'https://petstore3.swagger.io/api/v3/openapi.json'], // OpenAPI spec
    env: {
      // You can set environment variables here
      // API_KEY: process.env.YOUR_API_KEY,
    },
  },
});

async function main() {
  try {
    // Retrieve tools from the MCP server
    const tools = await mcpClient.tools();

    // Generate text using the AI SDK with MCP tools
    const { text } = await generateText({
      model,
      prompt: 'List all available pets in the pet store using the API.',
      tools, // Pass the MCP tools to the model
    });

    console.log('Generated text:', text);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Always close the MCP client to release resources
    await mcpClient.close();
  }
}

main();

Configuración

La configuración se gestiona mediante variables de entorno, opciones de línea de comandos o un archivo de configuración JSON:

Opciones de Línea de Comandos

# Start with specific OpenAPI spec file
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --overlays=./path/to/overlay.json,https://example.com/api/overlay.json

# Include only specific operations (supports glob patterns)
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

# Specify target API URL
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com

# Add custom headers to all API requests
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --headers='{"X-Api-Version":"1.0.0"}'

# Disable the X-MCP header
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --disableXMcp

Variables de Entorno

Puedes configurarlas en un archivo .env o directamente en tu entorno:

  • OPENAPI_SPEC_PATH: Ruta al archivo de especificación OpenAPI
  • OPENAPI_OVERLAY_PATHS: Rutas separadas por comas a archivos JSON de overlay
  • TARGET_API_BASE_URL: URL base para llamadas a la API (sobrescribe los servidores OpenAPI)
  • MCP_WHITELIST_OPERATIONS: Lista separada por comas de IDs de operación o rutas URL a incluir (admite patrones glob como getPet* o GET:/pets/*)
  • MCP_BLACKLIST_OPERATIONS: Lista separada por comas de IDs de operación o rutas URL a excluir (admite patrones glob, se ignora si se usa la lista blanca)
  • API_KEY: Clave de API para la API de destino (si es necesaria)
  • SECURITY_SCHEME_NAME: Nombre del esquema de seguridad que requiere la clave de API
  • SECURITY_CREDENTIALS: Cadena JSON que contiene credenciales de seguridad para múltiples esquemas
  • CUSTOM_HEADERS: Cadena JSON que contiene cabeceras personalizadas para incluir en todas las solicitudes de API
  • HEADER_*: Cualquier variable de entorno que comience con HEADER_ se añadirá como cabecera personalizada (por ejemplo, HEADER_X_API_Version=1.0.0 añade la cabecera X-API-Version: 1.0.0)
  • DISABLE_X_MCP: Establécelo en true para deshabilitar la adición de la cabecera X-MCP: 1 a todas las solicitudes de API
  • CONFIG_FILE: Ruta a un archivo de configuración JSON

Configuración JSON

También puedes usar un archivo de configuración JSON en lugar de variables de entorno u opciones de línea de comandos. El servidor MCP buscará archivos de configuración en el siguiente orden:

  1. Ruta especificada por la opción de línea de comandos --config
  2. Ruta especificada por la variable de entorno CONFIG_FILE
  3. config.json en el directorio actual
  4. openapi-mcp.json en el directorio actual
  5. .openapi-mcp.json en el directorio actual

Ejemplo de archivo de configuración JSON:

{
  "spec": "./path/to/openapi-spec.json",
  "overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
  "targetUrl": "https://api.example.com",
  "whitelist": "getPets,createPet,/pets/*",
  "blacklist": "deletePet,/admin/*",
  "apiKey": "your-api-key",
  "securitySchemeName": "ApiKeyAuth",
  "securityCredentials": {
    "ApiKeyAuth": "your-api-key",
    "OAuth2": "your-oauth-token"
  },
  "headers": {
    "X-Custom-Header": "custom-value",
    "User-Agent": "OpenAPI-MCP-Client/1.0"
  },
  "disableXMcp": false
}

Un archivo de configuración de ejemplo completo con comentarios explicativos está disponible en config.example.json en el directorio raíz.

Precedencia de Configuración

Los ajustes de configuración se aplican en el siguiente orden de precedencia (de mayor a menor):

  1. Opciones de línea de comandos
  2. Variables de entorno
  3. Archivo de configuración JSON

Desarrollo

Instalación

# Clone the repository
git clone <repository-url>
cd openapi-to-mcp-generator

# Install dependencies
npm install

# Build the project
npm run build

Pruebas Locales

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

Personalización y Publicación de Tu Propia Versión

Puedes usar este repositorio como base para crear tu propio servidor OpenAPI a MCP personalizado. Esta sección explica cómo hacer un fork del repositorio, personalizarlo para tus APIs específicas y publicarlo como paquete.

Fork y Personalización

  1. Haz un fork del repositorio: Haz un fork de este repositorio en GitHub para crear tu propia copia que puedas personalizar.

  2. Añade tus especificaciones OpenAPI:

    # Create a specs directory if it doesn't exist
mkdir -p specs

# Add your OpenAPI specifications
cp path/to/your/openapi-spec.json specs/

# Add any overlay files
cp path/to/your/overlay.json specs/

  3. Configura los ajustes predeterminados: Crea un archivo de configuración personalizado que se incluirá con tu paquete:

    # Copy the example config
cp config.example.json config.json

# Edit the config to point to your bundled specs
# and set any default settings

  4. Actualiza package.json:

    {
  "name": "your-custom-mcp-server",
  "version": "1.0.0",
  "description": "Your customized MCP server for specific APIs",
  "files": [
    "dist/**/*",
    "config.json",
    "specs/**/*",
    "README.md"
  ]
}

  5. Asegúrate de que las especificaciones estén incluidas: El campo files en package.json (mostrado arriba) garantiza que tus especificaciones y archivo de configuración se incluyan en el paquete publicado.

Personalización del Flujo de Trabajo de GitHub

El repositorio incluye un flujo de trabajo de GitHub Actions para publicación automática en npm. Para personalizarlo para tu repositorio bifurcado:

  1. Actualiza el nombre del flujo de trabajo: Edita .github/workflows/publish-npm.yaml para actualizar el nombre si lo deseas:

    name: Publish My Custom MCP Package

  2. Establece el ámbito del paquete (si es necesario): Si quieres publicar bajo un ámbito de organización npm, descomenta y modifica la línea de ámbito en el archivo del flujo de trabajo:

    - name: Setup Node.js
  uses: actions/setup-node@v4
  with:
    node-version: "18"
    registry-url: "https://registry.npmjs.org/"
    # Uncomment and update with your organization scope:
    scope: "@your-org"

  3. Configura el token de npm: Añade tu token de npm como secreto de GitHub llamado NPM_TOKEN en la configuración de tu repositorio bifurcado.

Publicación de Tu Paquete Personalizado

Una vez que hayas personalizado el repositorio:

  1. Crea y sube una etiqueta (tag):

    # Update version in package.json (optional, the workflow will update it based on the tag)
npm version 1.0.0

# Push the tag
git push --tags

  2. GitHub Actions:

    • Compilará automáticamente el paquete
    • Actualizará la versión en package.json para que coincida con la etiqueta
    • Publicará en npm con tus especificaciones y configuración incluidas

Uso Después de la Publicación

Los usuarios de tu paquete personalizado pueden instalarlo y usarlo con npm:

# Install your customized package
npm install your-custom-mcp-server -g

# Run it
your-custom-mcp-server

Pueden sobrescribir tus ajustes predeterminados mediante variables de entorno u opciones de línea de comandos como se describe en la sección de Configuración.

Licencia

MIT