swagger-openapi-mcp

MCP server for querying Swagger/OpenAPI metadata efficiently from AI tools.

It is useful for large API projects where querying the generated OpenAPI contract is faster and more reliable than reading controller and DTO source code directly.

Features

• Load one or more OpenAPI JSON sources from URLs or local files.
• Search APIs by path, method, tag, summary, description, operation ID, parameter names, request schemas, and response schemas.
• Get exact API details by method + path.
• Inspect schema fields, required flags, descriptions, references, and enum values.
• Reverse lookup APIs by schema name.
• Export currently loaded OpenAPI JSON for offline use.
• Cache OpenAPI sources so clients can keep querying when an API service is temporarily unavailable.
• Revalidate cached URL sources with ETag and Last-Modified when supported.
• Ranked fuzzy search for partial terms, acronyms, and non-contiguous matches.
• Markdown and JSON response formats.
• Pagination and response truncation for large projects.

Requirements

• Node.js 18 or newer.
• An MCP client that supports stdio servers.

Install

npm install
npm run build

Configure Sources

Single Swagger/OpenAPI endpoint:

export OPENAPI_URL="http://localhost:8080/v3/api-docs"

Multiple Swagger/OpenAPI groups:

export OPENAPI_SOURCES="admin=http://localhost:8080/v3/api-docs/admin,public=http://localhost:8080/v3/api-docs/public"

Local exported JSON:

export OPENAPI_FILE="./openapi.json"

Optional cache:

export OPENAPI_CACHE_DIR=".cache/openapi"
export OPENAPI_CACHE_TTL_SECONDS="86400"

When OPENAPI_CACHE_DIR is set, each loaded source is cached. If the original file or URL is unavailable later, the server falls back to cache when possible.

For URL sources, the server stores ETag and Last-Modified response headers when present. Later refreshes send If-None-Match and If-Modified-Since; a 304 Not Modified response reuses the cached OpenAPI JSON without re-parsing a new document. If the remote server does not provide these headers, the server still fetches the latest JSON and updates the cache.

MCP Client Config

After building from source, configure your MCP client to run the compiled stdio server:

{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": ["./dist/index.js"],
      "environment": {
        "OPENAPI_SOURCES": "admin=http://localhost:8080/v3/api-docs/admin,public=http://localhost:8080/v3/api-docs/public",
        "OPENAPI_CACHE_DIR": ".cache/openapi",
        "OPENAPI_CACHE_TTL_SECONDS": "86400"
      }
    }
  }
}

If installed as a package, use the binary name instead:

{
  "mcpServers": {
    "openapi": {
      "command": "openapi-mcp-server",
      "environment": {
        "OPENAPI_URL": "http://localhost:8080/v3/api-docs"
      }
    }
  }
}

TLS Notes

For HTTPS Swagger/OpenAPI endpoints with a self-signed or untrusted test certificate, Node may fail with fetch failed during MCP startup. Prefer fixing the test certificate or installing the internal CA. For short-lived test environments only, you can disable Node TLS verification for this MCP process:

{
  "environment": {
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

Do not use NODE_TLS_REJECT_UNAUTHORIZED=0 for production or untrusted networks.

Tools

• openapi_refresh_index: reload OpenAPI sources.
• openapi_list_sources: list source groups and operation counts.
• openapi_list_tags: list API tags/modules.
• openapi_search_api: search APIs by natural keywords.
• openapi_get_api_detail: get full detail for one API.
• openapi_get_schema: inspect schema fields.
• openapi_find_api_by_schema: reverse lookup APIs by schema.
• openapi_export_documents: export loaded OpenAPI JSON to local files.

Typical AI Workflow

1. openapi_list_sources
2. openapi_list_tags
3. openapi_search_api({ "query": "product list" })
4. openapi_get_api_detail({ "method": "GET", "path": "/admin/products" })
5. openapi_get_schema({ "name": "ProductListResponse" })

Export Workflow

Export currently loaded documents:

{
  "output_dir": "./openapi-exports"
}

Then use an exported file as an offline source:

export OPENAPI_FILE="./openapi-exports/admin.openapi.json"

Development

npm install
npm run build
npm test

Notes

• The server is stdio-based and long-running. Run it through an MCP client.
• Tool logs go to stderr so stdout remains reserved for MCP protocol messages.
• If the API service is not running, use OPENAPI_FILE with exported JSON.
• For frequently changing APIs, call openapi_refresh_index after restarting the API service or regenerating Swagger/OpenAPI.

License

MIT