mcp-openapi-runner
The mcp-openapi-runner server exposes any OpenAPI 3.x API (JSON or YAML, local or remote) to Claude as natural language-accessible tools, with zero manual configuration.
Two core tools:
list_endpoints— Discover all available API operations, grouped by tag, with their operationIds, HTTP methods, paths, and parameterscall_endpoint— Execute any operation by specifying itsoperationId, along with path/query/headerparametersand abodyfor POST/PUT/PATCH requests
Additional capabilities:
Automatically generates tool schemas by resolving
$refreferences directly from the OpenAPI specSupports Bearer token, API key, and Basic authentication via environment variables
Filter exposed endpoints by path, tag, or operationId pattern
Override the base server URL and add custom headers to all requests
Works with MCP clients like Claude Desktop, Claude Code, Cursor, and Cline
Typical workflow: Start with list_endpoints to discover what's available, then use call_endpoint with the appropriate operationId to take action — for example, listing/adding/updating pets, managing store inventory, or handling user accounts in the Swagger Petstore demo.
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 |
Related MCP server: FastMCP OpenAPI
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-resolvedAuto-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
--filterCustom headers — pass arbitrary headers with
--headerServer URL override — point at staging/local with
--server-urlTwo-tool design — simple
list_endpoints→call_endpointworkflowWorks 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 |
| Bearer token → |
| API key value |
| Header name for API key (default: |
| HTTP Basic auth username |
| 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 helpExamples
# 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.jsonTools
mcp-openapi-runner exposes exactly two tools:
Tool | Description |
| Returns all operations grouped by tag with operationIds, methods, paths, and parameters |
| Executes any operation by |
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-parserApplies endpoint filter if
--filteris setRegisters 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
Available Tools
2 toolscall_endpointA
Call an endpoint in the Swagger Petstore - OpenAPI 3.0. Use list_endpoints first to discover available operationIds and their required parameters.
Inputs: operationId (required), parameters, body.
list_endpointsA
List all available endpoints in the Swagger Petstore - OpenAPI 3.0. Call this first to discover what operations are available and get their operationIds.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have completely distinct purposes: list_endpoints is for discovery and metadata retrieval, while call_endpoint is for executing operations. There is no overlap or ambiguity between them.
Both tools follow a consistent verb_noun pattern with clear, descriptive names (list_endpoints and call_endpoint). The naming convention is uniform and predictable throughout the set.
With only 2 tools, this server feels thin for its purpose of interacting with an OpenAPI specification. While it covers basic discovery and execution, it lacks tools for more advanced operations like schema inspection, parameter validation, or response handling, making the scope appear underdeveloped.
The toolset provides a minimal viable surface for calling endpoints and listing them, but there are notable gaps. For example, it lacks tools for managing authentication, handling different HTTP methods explicitly, or validating requests against the OpenAPI schema, which could limit agent effectiveness in complex scenarios.
Maintenance
Related MCP Connectors
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
The OpenRouter for tools. One MCP connection gives any AI agent 254 hosted tools, pay per call.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAutomatically converts any OpenAPI specification or Postman Collection into an MCP server, enabling AI assistants like Claude to directly interact with REST APIs without writing any code.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceDynamically generates MCP tools from OpenAPI specifications, enabling AI assistants to interact with any REST API through natural language. Supports multiple APIs with authentication, parameter validation, and integration with Claude Desktop and LangChain.1MIT
- AlicenseNot gradedqualityDmaintenanceTurn any OpenAPI spec into a working MCP server — point it at a spec and Claude instantly gets a tool for every endpoint.MIT
- FlicenseNot gradedqualityDmaintenanceAutomatically converts OpenAPI specifications into MCP servers, allowing tools like Claude Desktop to interact with your REST APIs through a standard protocol.-