@ppcantidio/openapi-mcp-server

MCP Server that loads an OpenAPI 3.x spec and exposes it as tools for conversational API exploration — no more alt-tabbing to Swagger UI.

Quick Start

No install required — use npx:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "@ppcantidio/openapi-mcp-server",
        "--url",
        "https://api.example.com/openapi.json"
      ]
    }
  }
}

Add to Claude Code:

claude mcp add my-api -- npx @ppcantidio/openapi-mcp-server --url https://api.example.com/openapi.json

Configuration

| Option | Description | |---|---| | --url <url> | OpenAPI spec URL (JSON, OpenAPI 3.x) | | --ttl <seconds> | Auto-refresh interval (optional) | | OPENAPI_URL | Env var alternative to --url |

Multiple APIs

Register multiple instances, one per API:

{
  "mcpServers": {
    "spryx-api": {
      "command": "npx",
      "args": ["@ppcantidio/openapi-mcp-server", "--url", "https://api.spryx.ai/openapi.json"]
    },
    "stripe-api": {
      "command": "npx",
      "args": ["@ppcantidio/openapi-mcp-server", "--url", "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"]
    }
  }
}

Available Tools

| Tool | Description | |---|---| | list_endpoints | List all endpoints; filter by tag, method, deprecated | | get_endpoint | Full details for a specific endpoint (path + method), with $ref resolved | | search_endpoints | Free-text search across path, summary, description, operationId | | list_tags | All tags with descriptions and endpoint counts | | get_tag_endpoints | All endpoints for a specific tag | | get_schema | Named schema from components/schemas, with optional $ref resolution | | get_server_info | API title, version, server URLs, and totals | | refresh_spec | Re-fetch the spec without restarting the server |

Example Conversation

You: what modules does this API have?
Claude: [calls list_tags] → agents (8), billing (4), webhooks (3)

You: show me the agents endpoints
Claude: [calls get_tag_endpoints(tag="agents")] → list of 8 endpoints

You: what's the body for POST /v1/agents?
Claude: [calls get_endpoint(path="/v1/agents", method="POST")] → full details with resolved schema

You: is there anything webhook-related?
Claude: [calls search_endpoints(query="webhook")] → matching endpoints

Development

git clone https://github.com/ppcantidio/openapi-mcp-server
cd openapi-mcp-server
bun install

# Run from source
bun run dev --url https://api.example.com/openapi.json

# Test
bun test

# Lint
bun run lint

Tests

36 tests across unit (resolver) and integration (Petstore, medium API, Stripe subset fixtures).

License

MIT