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-openapi | With mcp-openapi |
|---|---|
| Write custom MCP server per API | One config line per API |
| Define tool schemas manually | Auto-generated from OpenAPI spec |
| Handle auth, params, body yourself | Built-in auth + parameter handling |
| Maintain code as API evolves | Spec changes = tools update automatically |
Quick start
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.
Example conversation
You: What pets are available? Add a new dog named Buddy.
Claude: Let me check what's available. [calls
list_endpoints→ discoversfindPetsByStatus,addPet, ...] [callscall_endpoint→findPetsByStatuswithstatus=available]There are 3 pets currently available. Now I'll add Buddy... [calls
call_endpoint→addPetwith{"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,
$refauto-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_endpointworkflow - 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"
}
}
}
}
| Variable | Description |
|---|---|
OPENAPI_BEARER_TOKEN | Bearer token → Authorization: Bearer <token> |
OPENAPI_API_KEY | API key value |
OPENAPI_API_KEY_HEADER | Header name for API key (default: X-Api-Key) |
OPENAPI_BASIC_USER | HTTP Basic auth username |
OPENAPI_BASIC_PASS | HTTP 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:
| Tool | Description |
|---|---|
list_endpoints | Returns all operations grouped by tag with operationIds, methods, paths, and parameters |
call_endpoint | Executes 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
- Loads the OpenAPI spec from the given URL or file path
- Dereferences all
$refschemas using@apidevtools/swagger-parser - Applies endpoint filter if
--filteris set - Registers two MCP tools with the connected client
list_endpointsgenerates a human+LLM-readable summary of all operationscall_endpointresolves params, builds the URL, attaches auth + custom headers, returns the response
Requirements
- Node.js 18+
- OpenAPI 3.x spec (JSON or YAML, local file or URL)
Contributing
Contributions welcome! See CONTRIBUTING.md for guidelines.
License
MIT