Skip to main content
Glama
kardaj

openapi-tools-mcp

by kardaj
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

OpenAPI Tools MCP and CLI

A Model Context Protocol server powered by fastMCP plus a JSON command-line interface for inspecting local or remote OpenAPI specs. Both interfaces expose the same summary, listing, filtering, retrieval, $ref resolution, and source-line behavior.

The server also publishes MCP metadata (instructions and website_url) to guide clients toward local-file OpenAPI inspection workflows.

Add as an MCP server

Add this server to your MCP client configuration (PyPI):

{
  "mcpServers": {
    "openapi-tools": {
      "command": "uvx",
      "args": [
        "--from",
        "openapi-tools-mcp",
        "openapi-tools-mcp"
      ]
    }
  }
}

This launches the openapi-tools-mcp entrypoint from PyPI via uvx.

TOML version (PyPI):

[mcp_servers.openapi-tools]
command = "uvx"
args = ["--from", "openapi-tools-mcp", "openapi-tools-mcp"]

You can also install directly from GitHub with uvx:

uvx --from git+ssh://git@github.com/kardaj/openapi-tools-mcp.git openapi-tools-mcp

Related MCP server: Swagger MCP

Use the command-line interface

Run the CLI ephemerally from PyPI with uvx --from:

uvx --from openapi-tools-mcp openapi-tools-cli info ./openapi.yaml | jq

For persistent use, install the package as a uv tool and call the dedicated CLI entry point:

uv tool install openapi-tools-mcp
openapi-tools-cli info ./openapi.yaml

Run openapi-tools-cli --help (or -h) for a single help page covering info, list, and get, including supported sections, output shapes, reference and filter behavior, and examples. Each command has its own section; shared source, header, and help arguments appear once. Command-specific help, such as openapi-tools-cli list --help, shows that command's details and examples.

Start with info to confirm the OpenAPI version, API metadata, and server base URLs. Use list to discover names, then get to inspect one item. These commands read specifications without calling API operations. info returns an object with openapi, info, and servers; list paths returns an array of {path, verbs} objects, while other sections return arrays of names. get returns {value, line_start, line_end}; line fields are zero-based source positions, or null when unavailable.

Both list and get support paths, schemas, parameters, responses, requestBodies, headers, securitySchemes, links, callbacks, and examples. list additionally supports tags, which lists tags used by operations; get does not retrieve tags. For get, supply an exact path such as /pet/{petId} or a component name such as Pet.

The CLI accepts local YAML or JSON paths, including paths with ~ and relative segments, and lowercase http:// or https:// URLs:

openapi-tools-cli info ./openapi.yaml
openapi-tools-cli list paths https://example.com/openapi.yaml
openapi-tools-cli get schemas Pet ~/specs/openapi.json

Repeat -H/--header for URL request headers. Header names and values are trimmed, values may contain additional colons, and the last identically spelled header name wins. Headers are rejected for local paths:

openapi-tools-cli info https://example.com/openapi.yaml \
  -H "Authorization: Bearer token" \
  -H "Accept: application/yaml"

list --glob matches path or item names using shell-style wildcards such as *, ?, and [abc]; quote patterns to prevent shell expansion. --tag filters paths by operation tags and schemas by tags/x-tags, and is ignored for other sections. Each occurrence accepts one tag, and repeated tags match any. For paths and schemas, an item must match both filters when --glob and --tag are supplied:

openapi-tools-cli list paths ./openapi.yaml --glob '/pets/*'
openapi-tools-cli list paths ./openapi.yaml --tag pet --tag admin

get resolves local #/... $ref values by default; external references cannot be resolved. Preserve all references, including external ones, with --no-resolve-refs:

openapi-tools-cli get schemas Pet ./openapi.yaml --no-resolve-refs

Successful operations write one newline-terminated JSON value to stdout, so their output can be piped to tools such as jq. Expected source, lookup, download, and parse failures write a concise message to stderr and exit with status 1; command syntax and header usage errors follow argparse conventions and exit with status 2.

Successful CLI URL downloads are cached for 15 minutes in the platform's conventional per-user cache location. Set OPENAPI_TOOLS_CACHE_DIR to use an exact alternative directory, for example OPENAPI_TOOLS_CACHE_DIR=/private/tmp/.cache/openapi-tools-mcp; an empty value leaves the platform default unchanged. Entries are shared across CLI processes and isolated by URL plus the complete normalized header mapping; concurrent requests for the same entry coordinate around one download while unrelated entries remain independent. An expired entry is used as stale fallback when refresh fails because of a network error or HTTP 5XX response, while HTTP 4XX and invalid refreshed content still fail. Cache directories and files are restricted to the invoking user, and cache identities contain only cryptographic digests rather than raw header names or values. The downloaded specification body may still contain sensitive API documentation and may persist in this private cache. Cache permission, corruption, or coordination failures, including an unavailable configured directory, degrade to an uncached request without changing a successful command's output. OPENAPI_TOOLS_CACHE_DIR affects only the CLI disk cache; the MCP server continues to use its process-local in-memory cache.

Available tools

  • spec_info(spec_path): Quickly summarize a spec source (OpenAPI version, title/description, servers). Use this first to confirm you're reading the right spec and its base URLs.

  • spec_list(section, spec_path, filter_by_glob?, filter_by_tag?): Enumerate keys within a spec section (e.g., all paths, schemas, or responses). Use to discover what exists before drilling into details.

  • spec_get(section, name, spec_path, resolve_refs=True): Retrieve a specific item from a section (e.g., one path or schema), with optional $ref resolution and source line numbers for precise navigation.

All tools accept either a readable OpenAPI YAML/JSON file path on the local filesystem or a URL source object. Local paths keep the existing behavior, including ~ expansion and absolute path resolution. An example spec lives at tests/openapi.example.yml.

URL source objects are passed through the existing spec_path argument:

{
  "url": "https://example.com/openapi.yaml",
  "headers": {
    "Authorization": "Bearer token",
    "Accept": "application/yaml"
  }
}

The headers object is optional and defaults to no extra request headers. Only http:// and https:// URLs are supported. Remote YAML and JSON documents are both supported.

Downloaded URL content is cached in memory for 15 minutes per MCP server process. Cache entries are keyed by URL plus the complete headers mapping, independent of header insertion order, so different authentication or content-negotiation inputs do not share responses. When an expired cached entry cannot be refreshed because of a network error or HTTP 5XX response, the stale cached content is used for that request. HTTP 4XX responses and unsupported URL schemes surface an error and do not use stale content. The MCP server does not read or write the CLI disk cache.

License

MIT

Available Tools

3 tools
spec_getSpec GetA

Retrieve a specific item from a local path string or URL source object, with optional $ref resolution and source line numbers. For remote specs, pass spec_path as {"url": "https://example.com/openapi.yaml", "headers": {"Header-Name": "value"}}; headers are optional, only http/https URLs are supported, and successful downloads are cached in memory for 15 minutes with stale fallback on network errors or HTTP 5XX refresh failures.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYes
sectionYes
spec_pathYes
resolve_refsNo

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations, the description carries the burden and does well: it discloses $ref resolution, source line numbers, http/https-only restriction, optional headers, 15-minute in-memory caching, and stale-fallback on network errors or HTTP 5XX. It omits any statement about auth requirements beyond headers and does not describe the return shape (no output schema).

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

Conciseness4/5

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

Front-loads purpose in the first clause and packs operational constraints into a single follow-up sentence. Dense but every clause carries information; the semicolon-chained second sentence is slightly run-on but not padded.

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

Completeness3/5

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

For a 4-parameter read tool with no annotations and no output schema, the description covers the awkward spec_path union and caching semantics well, but leaves the semantics of 'section' and 'name' — two of the three required parameters — completely unaddressed.

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 coverage is 0%, so the description must compensate. It does explain spec_path's object form (url/headers) and implies resolve_refs via 'optional $ref resolution', but the required parameters 'section' and 'name' are never explained in the description or schema, leaving the two central selectors undocumented.

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?

States a specific verb ('Retrieve') and resource ('a specific item') and clarifies the two input forms (local path string or URL source object). It implies distinction from spec_list/spec_info by scoping to a single item, but never names the siblings explicitly.

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

Usage Guidelines3/5

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

Gives concrete guidance on how to invoke it for remote specs and constrains source types to http/https, but provides no explicit when-to-use vs spec_list/spec_info, no prerequisites, and no statement of when a local path is preferable to a URL.

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

spec_infoSpec InfoA

Quickly summarize an OpenAPI spec from a local path string or URL source object. For remote specs, pass {"url": "https://example.com/openapi.yaml", "headers": {"Header-Name": "value"}}; headers are optional, only http/https URLs are supported, and successful downloads are cached in memory for 15 minutes with stale fallback on network errors or HTTP 5XX refresh failures.

ParametersJSON Schema
NameRequiredDescriptionDefault
spec_pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: it discloses the 15-minute in-memory cache, stale fallback on network errors and HTTP 5XX refresh failures, http/https-only URL support, and that headers are optional. It does not mention authentication or rate limits, but the caching/fallback behavior is genuinely useful operational context.

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

Conciseness4/5

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

Two sentences, front-loaded with the core action before the remote-spec handling details. The second sentence is dense with several facts, but every clause (cache duration, fallback conditions, scheme restriction) carries information and none is wasted.

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?

An output schema exists, so return values need not be explained, and the description adequately covers both input forms plus caching/error behavior. For a one-parameter tool this is close to complete; only sibling routing guidance is missing.

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 schema has 0% description coverage and only declares spec_path as anyOf string|object with no field detail. The description compensates by spelling out the object form ({url, headers}) and clarifying that headers are optional, which the schema alone would leave ambiguous.

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?

States a specific verb ('summarize') and resource ('an OpenAPI spec'), which distinguishes it from sibling spec_get (retrieve raw) and spec_list (enumerate). However, it never explicitly contrasts itself with those siblings, so the differentiation is inferred from the verb rather than stated.

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

Usage Guidelines3/5

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

It explains how to use the tool for remote specs (the {url, headers} form) but gives no explicit guidance on when to pick this over spec_get or spec_list. Usage is implied by 'summarize' rather than declared.

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

spec_listSpec ListA

Enumerate keys within a spec section from a local path string or URL source object. For remote specs, pass spec_path as {"url": "https://example.com/openapi.yaml", "headers": {"Header-Name": "value"}}; headers are optional, only http/https URLs are supported, and successful downloads are cached in memory for 15 minutes with stale fallback on network errors or HTTP 5XX refresh failures.

ParametersJSON Schema
NameRequiredDescriptionDefault
sectionYes
spec_pathYes
filter_by_tagNo
filter_by_globNo

TDQS

A3.6/5.0
Behavior4/5

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

With no annotations, the description carries the full behavioral burden and does substantial work: it discloses an in-memory 15-minute cache, stale fallback on network errors, and 5XX refresh-failure behavior, plus the http/https-only restriction. It omits read-only confirmation, permission requirements, and return/error shape, but the caching and failure semantics are unusually rich.

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

Conciseness4/5

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

Front-loaded with the core action, then the remote-spec mechanics in one dense sentence with no filler. It drifts toward run-on length in the caching clause but every clause conveys actionable detail.

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

Completeness3/5

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

For a 4-parameter tool with no annotations and no output schema, the description covers the fetch mechanics well but leaves the filtering parameters and the expected return ('keys' format) unexplained. It is adequate to invoke the tool, but an agent would have to guess at filter semantics.

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 0% across 4 parameters, so the description must compensate. It documents spec_path thoroughly (string path vs. {url, headers} object with optional headers), but says nothing about 'section', 'filter_by_tag', or 'filter_by_glob', leaving three parameters undocumented in both schema and text.

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?

States a specific verb and resource: 'Enumerate keys within a spec section,' which is distinguishable from spec_get (retrieval) and spec_info (metadata) even without naming them. It is clear what the tool does, but the description never explicitly contrasts itself with the sibling tools.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the tool is for listing keys in a section. The remote-source paragraph explains how to supply a URL, which is useful operational guidance, but there is no when-to-use-this-vs-spec_get/spec_info guidance and no exclusions or prerequisites.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.2.0
    • First observedspec_get
    • First observedspec_info
    • First observedspec_list
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

spec_info summarizes the whole spec, spec_list enumerates keys within a section, and spec_get retrieves a specific item. These are distinct operations with clear scope boundaries, though info and get could be slightly confused without the descriptions.

Naming Consistency5/5

All three tools use a consistent spec_<action> pattern: spec_info, spec_list, spec_get. The naming is predictable and easy to parse.

Tool Count5/5

Three tools are well-suited for a lightweight OpenAPI spec inspection server. Each tool earns its place for summary, enumeration, and retrieval without redundancy.

Completeness4/5

The set covers core read-only exploration: summarize, list keys, and get items with optional $ref resolution. Minor gaps such as search, validation, or diff operations exist but are not essential for the apparent inspection purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Swagger MCP

    yangyaofei
    A
    license
    Not graded
    quality
    D
    maintenance
    Loads and queries OpenAPI/Swagger documents, providing tools to list APIs, get details, search endpoints, and manage schemas for efficient API exploration.
    4
    MIT

  • swagger-api-mcp-server

    NekoTarou
    A
    license
    A
    quality
    C
    maintenance
    Parses Swagger 2.0 and OpenAPI 3.x specifications, exposing API endpoints, schemas, and authentication through MCP tools with local caching to reduce token usage.
    11
    12 npm
    1
    MIT

  • swagger-mcp

    emreycolakoglu
    A
    license
    A
    quality
    D
    maintenance
    A read-only MCP server for navigating OpenAPI / Swagger specifications, enabling agents to search endpoints, retrieve parameters and schemas, and inspect authentication without loading the full spec into context.
    9
    6 npm
    MIT