mcp-openapi-runner MCP Server

mcp-openapi

Turn any OpenAPI spec into MCP tools for Claude — instantly.

Point mcp-openapi 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.

Quick start

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

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

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

Example conversation

You: What pets are available, and add a new dog named Buddy

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

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

Done! Buddy has been added with ID 12345.

Authentication

Pass credentials via environment variables:

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

Tools

mcp-openapi exposes exactly two tools:

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

Using a local spec file

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "mcp-openapi", "--spec", "/path/to/your/openapi.yaml"]
    }
  }
}

Supports both JSON and YAML specs. All $ref references are resolved automatically.

Requirements

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

Real-world examples

Stripe API:

["--spec", "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json"]

GitHub REST API:

["--spec", "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json"]

Your internal API:

["--spec", "http://localhost:8080/openapi.json"]

CLI usage

# From URL
npx mcp-openapi --spec https://api.example.com/openapi.json

# From file
npx mcp-openapi --spec ./openapi.yaml

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

# Help
npx mcp-openapi --help

How it works

1. At startup, loads the spec from the given URL or file path
2. Dereferences all $ref schemas using @apidevtools/swagger-parser
3. Registers two MCP tools with the connected client
4. list_endpoints generates a human+LLM-readable summary of all operations
5. call_endpoint resolves path params, builds the URL, attaches auth headers, and returns the response

License

MIT