Skip to main content
Glama
saurav61091

mcp-openapi-runner

by saurav61091
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

mcp-openapi

npm version CI License: MIT Node.js MCP

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

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

  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

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 tools
call_endpointA

Call an endpoint in the Swagger Petstore - OpenAPI 3.0. Use list_endpoints first to discover available operationIds and their required parameters.

ParametersJSON Schema
NameRequiredDescriptionDefault
operationIdYesThe operationId from list_endpoints, e.g. 'getPetById' or 'createUser'
parametersNoPath, query, and header parameters as key-value pairs
bodyNoRequest body for POST/PUT/PATCH requests (object or string)

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. While it mentions the need to use 'list_endpoints' first for discovery, it doesn't describe what happens when the tool is invoked (e.g., HTTP method implications, error handling, authentication requirements, rate limits, or what the response looks like). For a tool that makes API calls, this leaves significant behavioral gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise - two sentences that each earn their place. The first sentence establishes the core purpose, and the second provides essential usage guidance. There's zero waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that makes API calls with 3 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, how errors are handled, authentication requirements, or the implications of different HTTP methods. The usage guidance is helpful but doesn't compensate for the missing behavioral context needed for effective tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond what the schema provides - it mentions 'operationId' and 'parameters' in the context of discovery but doesn't provide additional semantic context about how these parameters interact or when to use 'body' versus 'parameters'. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Call an endpoint') and the target resource ('in the Swagger Petstore - OpenAPI 3.0'), providing a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from its sibling 'list_endpoints' beyond mentioning it should be used first for discovery, which is more of a usage guideline than a purpose distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool ('Use list_endpoints first to discover available operationIds and their required parameters'), providing clear guidance on prerequisites and the relationship with the sibling tool. This tells the agent exactly how to approach using this tool effectively.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that this is a read-only discovery tool ('List all available endpoints'), which implies safe, non-destructive behavior. However, it lacks details on potential rate limits, authentication needs, or response format, leaving some behavioral aspects unspecified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose in the first sentence and follows with a concise usage guideline. Every sentence earns its place by providing essential information without redundancy, making it efficiently structured and appropriately sized for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is largely complete. It explains what the tool does and when to use it. However, it could be slightly more complete by hinting at the response format (e.g., list of endpoints with operationIds), though this is a minor gap for such a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0 parameters with 100% coverage, meaning no parameters are documented in the schema. The description does not mention any parameters, which is appropriate since none exist. It adds value by explaining the tool's purpose and usage, compensating for the lack of parameter documentation in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('List all available endpoints') and resource ('in the Swagger Petstore - OpenAPI 3.0'), distinguishing it from the sibling tool 'call_endpoint' which would execute operations rather than list them. The phrase 'Call this first to discover what operations are available' reinforces its distinct discovery purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage guidance: 'Call this first to discover what operations are available and get their operationIds.' This indicates when to use this tool (as an initial discovery step) and implicitly suggests an alternative (using 'call_endpoint' once operations are known), making it clear in context with the sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count2/5

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.

Completeness3/5

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

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • OpenAPI to MCP

    procoders
    A
    license
    Not graded
    quality
    D
    maintenance
    Automatically 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

  • FastMCP OpenAPI

    Agarwal-Saurabh
    A
    license
    Not graded
    quality
    D
    maintenance
    Dynamically 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.
    1
    MIT

  • FastMCP Gateway

    4human-ai
    F
    license
    Not graded
    quality
    D
    maintenance
    Automatically converts OpenAPI specifications into MCP servers, allowing tools like Claude Desktop to interact with your REST APIs through a standard protocol.

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/saurav61091/mcp-openapi'

If you have feedback or need assistance with the MCP directory API, please join our Discord server