OpenAPI al servidor MCP

Una herramienta que crea servidores MCP (Protocolo de Contexto de Modelo) a partir de las especificaciones de OpenAPI/Swagger, lo que permite que los asistentes de IA interactúen con tus API. Crea tus propios MCP personalizados y con tu marca para API o servicios específicos.

Descripción general

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

Características

Carga dinámica de especificaciones OpenAPI desde archivos o URL HTTP/HTTPS
Compatibilidad con superposiciones OpenAPI cargadas desde archivos o URL 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 conservació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
Alternativas de descripción jerárquica (descripción de la operación → resumen de la operación → resumen de la ruta)
Compatibilidad con encabezados HTTP personalizados a través de variables de entorno y CLI
Encabezado X-MCP para seguimiento e identificación de solicitudes de API
Compatibilidad con extensiones x-mcp personalizadas en el nivel de ruta para anular los nombres y descripciones de las herramientas

Uso con asistentes de IA

Esta herramienta crea un servidor MCP que permite a los asistentes de IA interactuar con las API definidas por las especificaciones de OpenAPI. La principal forma de usarlo es configurar el asistente de IA para que se ejecute directamente como una herramienta MCP.

Configuración en Claude Desktop

Asegúrese de tener Node.js instalado en su computadora
Abra Claude Desktop y navegue a Configuración > Desarrollador
Edite el archivo de configuración (o se creará si no existe):
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Ventanas: %APPDATA%\Claude\claude_desktop_config.json
Agregue esta configuración (personalícela según sea necesario):

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}

Reiniciar Claude Desktop
Ahora deberías ver un icono de martillo en el cuadro de entrada del chat. Haz clic en él para acceder a las herramientas de la API.

Personalización de la configuración

Puede ajustar la matriz args para personalizar su servidor MCP con varias opciones:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--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 el cursor

Cree un archivo de configuración en una de estas ubicaciones:
- Específico del proyecto: .cursor/mcp.json en el directorio de su proyecto
- Global: ~/.cursor/mcp.json en su directorio de inicio
Agregue esta configuración (ajústela según sea necesario para su API):

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}

Reiniciar el cursor o recargar la ventana

Uso con Vercel AI SDK

También puede utilizar este servidor MCP directamente en sus aplicaciones JavaScript/TypeScript utilizando el cliente MCP del SDK de Vercel AI:

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', '@tyktechnologies/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 administra a través de 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
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyktechnologies/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)
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

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

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

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

Variables de entorno

Puede configurarlos en un archivo .env o directamente en su entorno:

OPENAPI_SPEC_PATH : Ruta al archivo de especificaciones de OpenAPI
OPENAPI_OVERLAY_PATHS : Rutas separadas por comas para superponer archivos JSON
TARGET_API_BASE_URL : URL base para llamadas API (anula los servidores OpenAPI)
MCP_WHITELIST_OPERATIONS : Lista separada por comas de ID de operaciones o rutas URL para incluir (admite patrones glob como getPet* o GET:/pets/* )
MCP_BLACKLIST_OPERATIONS : Lista separada por comas de ID de operaciones o rutas URL para excluir (admite patrones glob, se ignora si se usa una lista blanca)
API_KEY : Clave API para la API de destino (si es necesario)
SECURITY_SCHEME_NAME : Nombre del esquema de seguridad que requiere la clave API
SECURITY_CREDENTIALS : cadena JSON que contiene credenciales de seguridad para múltiples esquemas
CUSTOM_HEADERS : cadena JSON que contiene encabezados personalizados para incluir en todas las solicitudes de API
HEADER_* : Cualquier variable de entorno que comience con HEADER_ se agregará como un encabezado personalizado (por ejemplo, HEADER_X_API_Version=1.0.0 agrega el encabezado X-API-Version: 1.0.0 )
DISABLE_X_MCP : Establézcalo como true para deshabilitar la adición del encabezado X-MCP: 1 a todas las solicitudes de API
CONFIG_FILE : Ruta a un archivo de configuración JSON

Configuración JSON

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

Ruta especificada por la opción de línea de comandos --config
Ruta especificada por la variable de entorno CONFIG_FILE
config.json en el directorio actual
openapi-mcp.json en el directorio actual
.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):

Opciones de línea de comandos
Variables de entorno
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

Personalizar y publicar su propia versión

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

Bifurcación y personalización

Bifurcar el repositorio : bifurca este repositorio en GitHub para crear tu propia copia que puedas personalizar.
Agregue sus 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/
Configurar ajustes predeterminados : Cree un archivo de configuración personalizado que se incluirá con su 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
Actualizar 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" ] }
Asegúrese de que las especificaciones estén incluidas : el campo files en package.json (que se muestra arriba) garantiza que sus especificaciones y archivo de configuración se incluirán en el paquete publicado.

Personalizar el flujo de trabajo de GitHub

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

Actualizar el nombre del flujo de trabajo : edite .github/workflows/publish-npm.yaml para actualizar el nombre si lo desea:
name: Publish My Custom MCP Package
Establecer el alcance del paquete (si es necesario) : si desea publicar bajo un alcance de organización npm, descomente y modifique la línea de alcance en el archivo de 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"
Configurar el token npm : agregue su token npm como un secreto de GitHub llamado NPM_TOKEN en la configuración de su repositorio bifurcado.

Publicación de su paquete personalizado

Una vez que haya personalizado el repositorio:

Crear y enviar una etiqueta :
# 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
Las acciones de GitHub harán lo siguiente:
- Construir automáticamente el paquete
- Actualizar la versión en package.json para que coincida con la etiqueta
- Publique en npm con sus especificaciones y configuración incluidas

Uso después de la publicación

Los usuarios de su 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 anular su configuración predeterminada a través de variables de entorno u opciones de línea de comando como se describe en la sección Configuración.

Licencia

Instituto Tecnológico de Massachusetts (MIT)

OpenAPI to MCP Server

Integrations