Labsco
saurav61091 logo

mcp-openapi-runner

from saurav61091

Turn any OpenAPI spec into callable MCP tools for Claude — point at any OpenAPI 3.x spec and Claude can call every endpoint through natural language.

🔥🔥🔥🔥✓ VerifiedAccount requiredNeeds API keys
#email#automation#payments#git#project-mgmt

mcp-openapi

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.

Why mcp-openapi?

Without mcp-openapiWith mcp-openapi
Write custom MCP server per APIOne config line per API
Define tool schemas manuallyAuto-generated from OpenAPI spec
Handle auth, params, body yourselfBuilt-in auth + parameter handling
Maintain code as API evolvesSpec changes = tools update automatically

Example conversation

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.

Features

  • 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

Ready-to-use configs

Stripe

{
  "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_..."
      }
    }
  }
}

GitHub REST API

{
  "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_..."
      }
    }
  }
}

Your internal API

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

Jira (Atlassian)

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

Authentication

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"
      }
    }
  }
}
VariableDescription
OPENAPI_BEARER_TOKENBearer token → Authorization: Bearer <token>
OPENAPI_API_KEYAPI key value
OPENAPI_API_KEY_HEADERHeader name for API key (default: X-Api-Key)
OPENAPI_BASIC_USERHTTP Basic auth username
OPENAPI_BASIC_PASSHTTP Basic auth password

CLI options

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

Examples

# 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

Tools

mcp-openapi-runner exposes exactly two tools:

ToolDescription
list_endpointsReturns all operations grouped by tag with operationIds, methods, paths, and parameters
call_endpointExecutes any operation by operationId with path/query/header/body parameters

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

How it works

  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