Turn any OpenAPI spec into MCP tools for Claude — zero config, instant API access.

Point mcp-openapi-runner at any OpenAPI 3.x spec and Claude can call every endpoint through natural language. No custom integration code. No manual tool definitions. One line of config.

Add to your Claude Desktop / Claude Code / Cursor / Cline MCP config:

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://petstore3.swagger.io/api/v3/openapi.json"]
    }
  }
}

That's it. Claude can now discover and call every endpoint in that API.

You: What pets are available? Add a new dog named Buddy.

Claude: Let me check what's available. [calls list_endpoints → discovers findPetsByStatus, addPet, ...] [calls call_endpoint → findPetsByStatus with status=available]

There are 3 pets currently available. Now I'll add Buddy... [calls call_endpoint → addPet with {"name":"Buddy","status":"available"}]

Done! Buddy has been added with ID 12345.

• Zero config — just point at a spec URL or file
• Any OpenAPI 3.x spec — JSON or YAML, local or remote, $ref auto-resolved
• Auto-generated operationIds — works even when the spec doesn't define them
• Built-in auth — Bearer, API key, Basic auth via environment variables
• Endpoint filtering — only expose the endpoints you need with --filter
• Custom headers — pass arbitrary headers with --header
• Server URL override — point at staging/local with --server-url
• Two-tool design — simple list_endpoints → call_endpoint workflow
• Works everywhere — Claude Desktop, Claude Code, Cursor, Cline, any MCP client

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "sk_test_..."
      }
    }
  }
}

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner",
        "--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json",
        "--filter", "repos"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "ghp_..."
      }
    }
  }
}

{
  "mcpServers": {
    "internal": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "http://localhost:8080/openapi.json"],
      "env": {
        "OPENAPI_API_KEY": "dev-key-123"
      }
    }
  }
}

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner",
        "--spec", "https://dac-static.atlassian.com/cloud/jira/platform/swagger-v3.v3.json",
        "--server-url", "https://your-domain.atlassian.net",
        "--filter", "issue"],
      "env": {
        "OPENAPI_BASIC_USER": "you@company.com",
        "OPENAPI_BASIC_PASS": "your-api-token"
      }
    }
  }
}

Pass credentials via environment variables:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-runner", "--spec", "https://api.example.com/openapi.json"],
      "env": {
        "OPENAPI_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

npx mcp-openapi-runner --spec <url-or-path> [options]

Options:
  --spec         Path or URL to an OpenAPI 3.x spec (JSON or YAML)
  --server-url   Override the base URL from the spec
  --filter       Only expose endpoints matching a pattern (path, tag, or operationId)
  --header       Add custom header to all requests ("Name: Value", repeatable)
  --help         Show help

# Basic usage
npx mcp-openapi-runner --spec https://petstore3.swagger.io/api/v3/openapi.json

# Only pet-related endpoints
npx mcp-openapi-runner --spec ./openapi.yaml --filter pets

# Point at local dev server
npx mcp-openapi-runner --spec ./openapi.yaml --server-url http://localhost:3000

# Custom headers
npx mcp-openapi-runner --spec ./openapi.yaml --header "X-Tenant: acme" --header "X-Debug: true"

# With auth
OPENAPI_BEARER_TOKEN=mytoken npx mcp-openapi-runner --spec https://api.example.com/openapi.json

mcp-openapi-runner exposes exactly two tools:

The two-tool design means Claude always has a clear workflow: discover → call.

1. Loads the OpenAPI spec from the given URL or file path
2. Dereferences all $ref schemas using @apidevtools/swagger-parser
3. Applies endpoint filter if --filter is set
4. Registers two MCP tools with the connected client
5. list_endpoints generates a human+LLM-readable summary of all operations
6. call_endpoint resolves params, builds the URL, attaches auth + custom headers, returns the response

• Node.js 18+
• OpenAPI 3.x spec (JSON or YAML, local file or URL)

Contributions welcome! See CONTRIBUTING.md for guidelines.

MIT