@abhishekkumar00019/swagger-mcp

Динамический сервер Model Context Protocol (MCP), который преобразует любую спецификацию Swagger 2.0 или OpenAPI 3.x в вызываемые MCP-инструменты на лету.

Укажите URL любой спецификации OpenAPI/Swagger в формате JSON или YAML — и каждая конечная точка API автоматически станет интерактивным инструментом для Claude, Copilot, ChatGPT, Cursor, Windsurf и других клиентов с поддержкой MCP.

✨ Возможности

• 🔄 Динамическая генерация инструментов — автоматически разбирает спецификации Swagger 2.0 и OpenAPI 3.x при запуске.

• 🛠️ Ноль шаблонного кода — укажите URL спецификации, и каждая конечная точка мгновенно станет MCP-инструментом.

• 🔐 Гибкая поддержка аутентификации — Bearer-токены, API-ключи и Basic Auth настраиваются без усилий через переменные окружения или флаги CLI.

• 🌐 Умное определение базового URL — автоматически выводит базовый URL из конфигурации → определения сервера в спецификации → исходного URL спецификации.

• 🔁 Горячая перезагрузка — повторно загружает и разбирает спецификацию на лету с помощью инструмента _swagger_mcp_reload.

• 📝 Богатые схемы и описания — преобразует параметры OpenAPI и тела запросов в строгие JSON-схемы для точного вызова инструментов LLM.

• ⏱️ Настраиваемые тайм-ауты и пользовательские заголовки — легко задавайте собственные заголовки запросов и пороги тайм-аута.

Related MCP server: Swagger to MCP

🚀 Быстрый старт

Вариант A: напрямую через npx (установка не требуется)

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

Вариант B: глобальная установка через NPM

npm install -g @abhishekkumar00019/swagger-mcp

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

Вариант C: локальная настройка репозитория

1. Клонируйте репозиторий и установите зависимости:

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

2. Соберите проект:

   npm run build

3. Запустите локально:

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

⚙️ Конфигурации MCP-клиентов

Ниже приведены примеры конфигураций для популярных MCP-клиентов с использованием npx @abhishekkumar00019/swagger-mcp.

1. Claude Desktop

Добавьте в ваш 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)

Добавьте напрямую через CLI Claude Code:

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

Или добавьте в .mcp.json в корне вашего проекта:

{
  "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

Добавьте в .vscode/mcp.json в вашем рабочем пространстве или в глобальные настройки 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

Добавьте в .cursor/mcp.json или настройте в 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

Добавьте в ~/.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)

Добавьте в cline_mcp_settings.json (или 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)

Прямой импорт спецификации OpenAPI (встроенные действия Custom GPT): ChatGPT Custom GPTs поддерживают спецификации OpenAPI нативно. Вы можете напрямую импортировать URL вашей Swagger/OpenAPI JSON/YAML спецификации в разделе Actions конструктора Custom GPT без необходимости в промежуточном сервере.

Через MCP HTTP/SSE шлюз: Если вы подключаете агентов ChatGPT или OpenAI к этому MCP-серверу через HTTP/SSE мост (например, с помощью supergateway или mcp-remote), запустите swagger-mcp с SSE-прокси:

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

8. Zed Editor

Добавьте в ~/.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"
      }
    }
  }
}

🔧 Справочник по конфигурации

Все параметры конфигурации можно задать через переменные окружения или аргументы CLI. SWAGGER_MCP_SPEC_URL — единственный обязательный параметр.

🔑 Примеры аутентификации

Несколько методов аутентификации можно задать одновременно:

# 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] Если указаны и Bearer, и Basic Auth, Basic Auth перезапишет заголовок Authorization. Комбинируйте Bearer-токен с заголовками API-ключа, если требуется несколько заголовков.

🏷️ Стратегия именования инструментов

Конечные точки из вашей спецификации OpenAPI преобразуются в MCP-инструменты в следующем порядке приоритета:

🧰 Встроенные мета-инструменты

📁 Структура проекта

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

📄 Лицензия

MIT