OpenAPI Swagger MCP

🔌 openapi-swagger-mcp

[npm version] [Node.js] [License: MIT]

Connect your AI coding agent to any Swagger 2.0 or OpenAPI 3.0 / 3.1 service from your local machine.

Most OpenAPI-to-MCP bridges generate one tool per endpoint. That works on a 10-route pet store and falls apart on a 400-route backend. openapi-swagger-mcp takes a different approach: it gives the agent 11 fixed tools to search specs, read schemas, dry-run requests, handle auth, and make real HTTP calls, no matter how many endpoints your API has.

flowchart LR  subgraph Machine["💻 Your Machine"]    Client["🤖 MCP Client\n(Claude, Cursor, VS Code, ...)"]    Server["⚙️ openapi-swagger-mcp\n(11 fixed tools)"]    Inspector["🔎 Local Inspector UI\n(http://127.0.0.1)"]  end
  subgraph Targets["🌐 Your Non-Production APIs"]    Specs["📄 OpenAPI / Swagger Specs"]    Backend["🚀 API Services"]  end
  Client <-->|"stdio (MCP)"| Server  Server -->|"loads & indexes"| Specs  Server <-->|"HTTP / HTTPS"| Backend  Server -.->|"read-only trace"| Inspector

🔎 See what your agent actually sent

Chat summaries only tell you what the model thinks happened. When an agent chains five API calls, refreshes a token, and hits a 422, you want to see the real traffic.

The built-in Local Request Inspector opens a read-only web UI on 127.0.0.1 for your active MCP session:

• 🕒 Live activity timeline: Every MCP tool call is paired with the HTTP requests, redirects, and login/refresh runs it triggered. Offline preview_operation checks show up clearly with zero network traffic.
• 🧪 Side-by-side HTTP workbench: Check full URLs, query parameters, headers, cookies, request bodies, and formatted or hex responses. Secrets injected from your config stay masked by name.
• 📋 Schema checks & cURL export: Spot request or response fields that broke your OpenAPI contract, and copy a ready-to-run curl command for any exchange.

⚡ Try the built-in demo in 30 seconds

Want to click around the Inspector and test the tools before wiring up your own API? Run demo as your MCP server command (requires Node.js 22.19+):

npx -y @nhan7777/[email protected] demo

demo spins up a local mock backend on 127.0.0.1 (demo-shop and demo-account), turns on the Inspector, and serves MCP over stdio. Drop that command into your MCP client, then run the --inspector-url command printed on stderr in a local terminal to watch the agent work in your browser.

🚀 Quick start

1. Create an API config

Run init to generate a starter config.dev.yaml and a client snippet. It validates your inputs and never touches your editor's config files:

npx -y @nhan7777/[email protected] init \  --service orders \  --base-url http://localhost:8080/api/v1 \  --spec http://localhost:8080/v3/api-docs \  --out config.dev.yaml \  --client claude-code

💡 Tip: Add --bearer-env ORDERS_TOKEN if your API expects a Bearer token. --client accepts generic, claude-desktop, claude-code, cursor, vscode, windsurf, cline, codex, omp, or kiro.

Prefer writing YAML by hand? Create config.dev.yaml:

inspector:  enabled: true  port: 0
services:  orders:    baseUrl: http://localhost:8080/api/v1    # full URL prefix; overrides spec servers/basePath    spec: http://localhost:8080/v3/api-docs  # URL or relative file path like ./openapi.json

2. Check the config

npx -y @nhan7777/[email protected] --config /absolute/path/config.dev.yaml --check

--check validates syntax, environment variables, and local file paths offline ("ok": true, exit 0). To also fetch and validate your OpenAPI specs over the network, use --check-specs.

3. Register the server in your MCP client

Add this stdio entry to your MCP client config using the absolute path to config.dev.yaml (leave --check out of args):

{  "mcpServers": {    "api-dev": {      "command": "npx",      "args": [        "-y",        "@nhan7777/[email protected]",        "--config",        "/absolute/path/config.dev.yaml"      ]    }  }}

Need the exact config file path or CLI command for Claude Desktop, Claude Code, Cursor, VS Code / GitHub Copilot, Windsurf, Cline, Codex CLI, OMP, or Kiro? See the 🛠️ MCP Client Setup Guide.

4. Send a first prompt & open the Inspector

Reconnect the MCP server in your client and start with a safe, read-only prompt:

List the configured APIs, check whether the orders spec loaded, and show session.sessionId and session.inspector.state without calling any API endpoints.

Next, ask the agent to look up an endpoint and dry-run a request:

Find the order details endpoint in orders, show its required parameters, and preview a request for ID demo-123 without sending it.

If inspector.enabled is true, open the browser UI from your own terminal using the sessionId from list_apis:

npx -y @nhan7777/[email protected] \  --config /absolute/path/config.dev.yaml \  --inspector-url --session <session-id>

🔒 Keep the Inspector URL private: The #t=... fragment at the end of the URL is your local access token. Run --inspector-url in your own terminal and open it directly in a browser, not inside the AI chat. See the 🔎 Inspector Guide.

🧭 How a typical session flows

sequenceDiagram  autonumber  actor You  participant Agent as 🤖 AI Agent  participant MCP as ⚙️ openapi-swagger-mcp  participant API as 🚀 Target API
  You->>Agent: "Check order demo-123 in orders"  Agent->>MCP: list_apis / search_operations  MCP-->>Agent: matching endpoints + spec revision  Agent->>MCP: get_operation_schema (GET /orders/{id})  MCP-->>Agent: parameters, auth, response schema  Agent->>MCP: preview_operation (offline dry-run)  MCP-->>Agent: built URL, headers, validation (sent: false)  Agent->>MCP: invoke_operation  MCP->>API: GET /api/v1/orders/demo-123  API-->>MCP: 200 OK + JSON body  MCP-->>Agent: status, bodyView, schema diagnostics

1. 🔍 Discover: list_apis and search_operations locate the right endpoint and current spec revision.
2. 📐 Read the contract: get_operation_schema returns parameters, request body shape, auth requirements, and response schemas.
3. 🧪 Dry-run: preview_operation builds and validates the request locally (sent: false) without touching the network.
4. 🚀 Call: invoke_operation sends the real HTTP request (keeping intentional bad inputs intact for negative testing) and checks the response against the spec.
5. 🔎 Audit: Open the Inspector to review every tool call, HTTP exchange, auth run, and payload.

⚠️ Two rules to keep in mind

• Point at non-production environments (local, test, or staging). invoke_operation sends real POST, PUT, PATCH, and DELETE requests with no undo button. Keep your MCP client's tool confirmation prompts enabled.
• Know what reaches your LLM provider. This server runs locally over stdio with zero telemetry. However, any tool output your assistant reads is sent by your MCP client to your model provider. Load credentials with fromEnv or fromFile instead of pasting tokens into chat.

🧰 The 11 fixed tools

📚 Documentation

📦 Alternative installs & package details

• Global install: npm install -g @nhan7777/[email protected] (binary: openapi-swagger-mcp). Always include the @nhan7777/ scope; the unscoped openapi-swagger-mcp package on npm is a different project.
• Official MCP Registry: Published as io.github.nhan7777/openapi-swagger-mcp on the Official MCP Registry. Everything runs locally on your machine; never upload private configs or tokens to third-party web hosts.
• License: MIT. Third-party notices are in THIRD_PARTY_NOTICES.md.