MCP OpenAPI Connector

Conéctese a cualquier API basada en OpenAPI con gestión de autenticación OAuth2 integrada.

GitHub
3
Prueba este MCPPatrocinado

Documentación

MCP OpenAPI Connector

Un servidor unificado de Protocolo de Contexto de Modelo (MCP) para conectar APIs basadas en OpenAPI con gestión de autenticación integrada. Este proyecto permite que Claude Desktop, Cursor y otros clientes compatibles con MCP interactúen con APIs basadas en OpenAPI autenticadas sin necesidad de servidores proxy separados.

Características

  • Arquitectura de Proceso Único: No se necesita un servidor proxy separado
  • Autenticación OAuth2 Integrada: Gestión y renovación automática de tokens
  • Integración OpenAPI: Genera automáticamente herramientas MCP a partir de especificaciones OpenAPI/Swagger
  • Sistema de Herramientas Extensible: Fácil de añadir herramientas y recursos personalizados
  • Manejo de Errores: Reintentos automáticos y recuperación de errores de autenticación
  • Configuración Sencilla: Un único archivo de configuración para todos los ajustes
  • Soporte para Múltiples APIs: Se adapta fácilmente a cualquier API basada en OAuth2

Instalación

Vía npm (Recomendado)

npm install -g @ssossan/mcp-openapi-connector

O úsalo directamente con npx:

npx @ssossan/mcp-openapi-connector

Desde el Código Fuente

git clone https://github.com/ssossan/mcp-openapi-connector.git
cd mcp-openapi-connector
npm install

Configuración Rápida (Recomendado)

Ejecuta el asistente de configuración interactivo:

npm run setup

Esto hará lo siguiente:

  • Recopilará la configuración de tu API mediante indicaciones interactivas
  • Generará el archivo generated/.env con tus ajustes
  • Creará generated/claude-desktop-config.json para una integración sencilla con Claude Desktop
  • Proporcionará instrucciones paso a paso para la configuración de Claude Desktop

Configuración Manual

Alternativamente, puedes configurarlo manualmente:

  1. Copia .env.example a .env:
cp .env.example .env
  1. Edita .env con tus credenciales de API:
CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
API_BASE_URL=https://api.example.com
AUTH_PATH=/oauth/token
OPENAPI_SPEC_PATH=./config/openapi.json

Uso

Modo de Desarrollo

Para desarrollo con recompilación automática:

npm run dev

Modo de Producción

Compila y ejecuta la versión compilada:

npm run build
npm start

Configuración de Claude Desktop

Añade esto al archivo de configuración de Claude Desktop:

Usando el paquete npm (Recomendado):

{
  "mcpServers": {
    "openapi-connector": {
      "command": "npx",
      "args": ["@ssossan/mcp-openapi-connector"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Usando instalación global:

{
  "mcpServers": {
    "openapi-connector": {
      "command": "mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Usando desde el código fuente:

{
  "mcpServers": {
    "openapi-connector": {
      "command": "node",
      "args": ["/path/to/mcp-openapi-connector/dist/mcp-openapi-connector.js"],
      "cwd": "/path/to/mcp-openapi-connector",
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "API_BASE_URL": "https://api.example.com",
        "AUTH_PATH": "/oauth/token",
        "OPENAPI_SPEC_PATH": "/path/to/openapi.json"
      }
    }
  }
}

Integración OpenAPI

El servidor genera automáticamente herramientas a partir de una especificación OpenAPI. Se requiere una especificación OpenAPI para que el servidor funcione.

  1. Coloca tu archivo de especificación OpenAPI (formato JSON) en el proyecto
  2. Establece la ruta en tu entorno:
OPENAPI_SPEC_PATH=./config/openapi.json
OPENAPI_TOOL_PREFIX=api_  # Optional: prefix for generated tool names
OPENAPI_INCLUDE_ONLY=listItems,createItem  # Optional: only include specific operations
OPENAPI_EXCLUDE=deleteItem  # Optional: exclude specific operations

El servidor generará automáticamente herramientas MCP a partir de todas las operaciones en tu especificación OpenAPI. Sin una especificación OpenAPI, el servidor solo proporcionará herramientas de prueba/depuración.

Herramientas Personalizadas

Crea herramientas personalizadas añadiendo un archivo JavaScript:

export default {
  register(server) {
    server.registerCustomTool('my_tool', {
      name: 'my_tool',
      description: 'My custom tool',
      inputSchema: {
        type: 'object',
        properties: {
          param: { type: 'string', required: true }
        }
      },
      apiEndpoint: '/my-endpoint',
      method: 'POST'
    });
  }
};

Luego establece CUSTOM_TOOLS_PATH en tu entorno:

CUSTOM_TOOLS_PATH=./src/tools/my-custom-tools.ts

Publicación en npm

Para mantenedores:

npm run build
npm test
npm publish --access public

Desarrollo

Scripts Disponibles

npm run dev          # Development mode with tsx
npm run build        # Compile TypeScript to JavaScript
npm start            # Build and run production version
npm run test         # Build and run test server
npm run test:dev     # Run test server in development mode
npm run typecheck    # Type check without compilation
npm run clean        # Remove build output

Desarrollo en TypeScript

Este proyecto está construido con TypeScript para una mejor seguridad de tipos y experiencia de desarrollo:

  • Código fuente: directorio src/
  • Salida de compilación: directorio dist/
  • Definiciones de tipos: archivos .d.ts generados automáticamente

Arquitectura

Claude Desktop ↔ MCP Server (stdio) → OpenAPI-based API
                    ↓
             TokenManager
           (OAuth2 handling)

Componentes Clave

  • src/mcp-openapi-connector.ts - Punto de entrada principal del servidor
  • src/lib/token-manager.ts - Gestión de tokens OAuth2 con caché
  • src/lib/saas-client.ts - Cliente HTTP con autenticación automática
  • src/lib/mcp-handler.ts - Manejo del protocolo MCP y registro de herramientas
  • src/lib/openapi-loader.ts - Analizador de especificaciones OpenAPI y generador de herramientas
  • src/types/ - Definiciones de tipos TypeScript

Migración desde v1.x

Si estás usando la versión anterior basada en gateway:

  1. Elimina la configuración del servidor proxy
  2. Actualiza la configuración de Claude Desktop para que apunte directamente a este servidor
  3. Usa las mismas variables de entorno (no se necesitan cambios)

Ejemplo: Uso con una API Genérica Basada en OpenAPI

Consulta el archivo config/openapi-example.json para ver una especificación OpenAPI de muestra que demuestra cómo estructurar tu API para la integración con MCP.

Solución de Problemas

Errores de Autenticación

  • Verifica que CLIENT_ID y CLIENT_SECRET sean correctos
  • Comprueba que AUTH_URL apunte al endpoint OAuth2 correcto
  • Asegúrate de que tus credenciales tengan los alcances necesarios

Problemas de Conexión

  • Comprueba que API_BASE_URL sea correcto
  • Verifica la conectividad de red
  • Revisa los registros del servidor para ver mensajes de error detallados

Modo de Depuración

Establece NODE_ENV=development para un registro detallado:

NODE_ENV=development npm run dev

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Licencia

MIT

Agradecimientos

Construido usando el SDK de Protocolo de Contexto de Modelo de Anthropic.