@abhishekkumar00019/swagger-mcp

Un servidor dinámico de Model Context Protocol (MCP) que convierte cualquier especificación Swagger 2.0 u OpenAPI 3.x en herramientas MCP invocables sobre la marcha.

Proporciónale cualquier URL de especificación OpenAPI/Swagger en JSON o YAML, y cada endpoint de API se convierte automáticamente en una herramienta interactiva para Claude, Copilot, ChatGPT, Cursor, Windsurf y otros clientes compatibles con MCP.

✨ Características

• 🔄 Generación dinámica de herramientas — Analiza automáticamente especificaciones Swagger 2.0 y OpenAPI 3.x al iniciar.

• 🛠️ Cero código repetitivo — Dale una URL de especificación y cada endpoint se expone al instante como una herramienta MCP.

• 🔐 Soporte de autenticación flexible — Tokens Bearer, claves de API y autenticación básica configurados sin esfuerzo mediante variables de entorno o flags de CLI.

• 🌐 Resolución inteligente de URL base — Deriva automáticamente la URL base desde la configuración → definición del servidor de la especificación → URL de origen de la especificación.

• 🔁 Recarga en caliente — Vuelve a obtener y analizar la especificación en vivo en tiempo de ejecución usando la herramienta _swagger_mcp_reload.

• 📝 Esquemas y descripciones enriquecidos — Traduce los parámetros de OpenAPI y los cuerpos de solicitud a esquemas JSON estrictos para una llamada precisa de herramientas LLM.

• ⏱️ Tiempos de espera configurables y cabeceras personalizadas — Configura fácilmente cabeceras de solicitud personalizadas y umbrales de tiempo de espera.

Related MCP server: Swagger to MCP

🚀 Inicio rápido

Opción A: Directamente mediante npx (sin necesidad de instalación)

SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json npx @abhishekkumar00019/swagger-mcp

Opción B: Instalación global de NPM

npm install -g @abhishekkumar00019/swagger-mcp

SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json swagger-mcp

Opción C: Configuración del repositorio local

1. Clona e instala las dependencias:

   git clone https://github.com/itachiuchihadev/swagger-mcp.git
   cd swagger-mcp
   npm install

2. Compila el proyecto:

   npm run build

3. Ejecuta localmente:

   SWAGGER_MCP_SPEC_URL=https://petstore.swagger.io/v2/swagger.json node dist/index.js

⚙️ Configuraciones de clientes MCP

A continuación se muestran configuraciones de ejemplo para clientes MCP populares usando npx @abhishekkumar00019/swagger-mcp.

1. Claude Desktop

Añádelo a tu claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json",
        "SWAGGER_MCP_BEARER_TOKEN": "your-api-token-here"
      }
    }
  }
}

2. Claude Code (CLI)

Añádelo directamente mediante la CLI de Claude Code:

claude mcp add swagger-mcp -- npx -y @abhishekkumar00019/swagger-mcp --spec-url https://petstore.swagger.io/v2/swagger.json

O añádelo a .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

3. GitHub Copilot / VS Code

Añádelo a .vscode/mcp.json en tu espacio de trabajo o en la configuración global de VS Code:

{
  "server": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json",
        "SWAGGER_MCP_API_KEY": "your-api-key"
      }
    }
  }
}

4. Cursor

Añádelo a .cursor/mcp.json o configúralo en Cursor Settings → Features → MCP:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

5. Windsurf

Añádelo a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

6. Roo Code / Cline (VS Code Extension)

Añádelo a cline_mcp_settings.json (o roo_code_mcp_settings.json):

{
  "mcpServers": {
    "swagger-mcp": {
      "command": "npx",
      "args": ["-y", "@abhishekkumar00019/swagger-mcp"],
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

7. ChatGPT & OpenAI (Custom GPTs / Assistants / API)

Importación directa de especificaciones OpenAPI (acciones nativas de Custom GPT): Los Custom GPTs de ChatGPT admiten especificaciones OpenAPI de forma nativa. Puedes importar directamente la URL de tu especificación Swagger/OpenAPI en JSON/YAML en la sección Actions del Custom GPT Builder sin necesidad de un servidor intermedio.

Mediante la puerta de enlace MCP HTTP/SSE: Si conectas agentes de ChatGPT o OpenAI a este servidor MCP mediante un puente HTTP/SSE (por ejemplo, usando supergateway o mcp-remote), inicia swagger-mcp con un proxy SSE:

npx supergateway --stdio "npx -y @abhishekkumar00019/swagger-mcp --spec-url https://petstore.swagger.io/v2/swagger.json" --port 8000

8. Zed Editor

Añádelo a ~/.config/zed/settings.json:

{
  "context_servers": {
    "swagger-mcp": {
      "command": {
        "path": "npx",
        "args": ["-y", "@abhishekkumar00019/swagger-mcp"]
      },
      "env": {
        "SWAGGER_MCP_SPEC_URL": "https://petstore.swagger.io/v2/swagger.json"
      }
    }
  }
}

🔧 Referencia de configuración

Todos los parámetros de configuración pueden proporcionarse mediante variables de entorno o argumentos de CLI. SWAGGER_MCP_SPEC_URL es el único parámetro obligatorio.

🔑 Ejemplos de autenticación

Se pueden configurar varios métodos de autenticación simultáneamente:

# Bearer Token
SWAGGER_MCP_BEARER_TOKEN=sk-your-token-here

# API Key (Custom Header)
SWAGGER_MCP_API_KEY=your-api-key
SWAGGER_MCP_API_KEY_HEADER=X-Custom-Key

# Basic Auth
SWAGGER_MCP_BASIC_USER=admin
SWAGGER_MCP_BASIC_PASS=secret123

[!NOTE] Si se especifican tanto Bearer como Basic Auth, Basic Auth sobrescribirá la cabecera Authorization. Combina el token Bearer con las cabeceras de API Key si se requieren varias cabeceras.

🏷️ Estrategia de nomenclatura de herramientas

Los endpoints de tu especificación OpenAPI se convierten en herramientas MCP utilizando el siguiente orden de prioridad:

🧰 Herramientas meta integradas

📁 Estructura del proyecto

swagger-mcp/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # Entry point & CLI argument parser
│   ├── server.ts             # MCP server initialization & tool registration
│   ├── swagger-parser.ts     # OpenAPI 2.0/3.x spec fetcher & parser
│   ├── tool-builder.ts       # Converts OpenAPI operations -> JSON Schema tools
│   ├── request-handler.ts    # Proxies MCP tool calls to HTTP endpoints
│   ├── auth.ts               # Authentication header builder
│   ├── config.ts             # Environment & CLI configuration manager
│   └── types.ts              # Shared TypeScript interfaces
└── dist/                     # Compiled JavaScript output

📄 Licencia

MIT