mcp-openapi-schema-explorer

This MCP server provides token-efficient, template-based access to OpenAPI (v3) and Swagger (v2) specifications via MCP Resource Templates. By exposing parameterized resource templates (for example, openapi://paths/{path}/{method} and other components), clients can explore large API definitions without loading the entire document into memory. The server supports loading specs from local files or remote URLs (Swagger v2.0 is automatically converted to OpenAPI v3.0 on load). Clients discover available resources through the template patterns rather than enumerating every path or component up front, enabling scalable exploration of large APIs.

To use it, add one of the provided MCP server entries to your client's configuration (npx or Docker are common methods). When using npx, you can pass the path or URL to your OpenAPI/Swagger spec and optionally set an output format (json, yaml, json-minified). When using Docker, point the container to your spec URL or mount a local file into the container. The server emphasizes resource templates over pre-enumerated resources, making it especially suitable for very large APIs where context window constraints matter.

Prerequisites:

• Node.js and npm (for local build or npx usage) or Docker (for Docker usage) installed on your machine
• Access to the internet for pulling packages/images

Option A: Global installation (optional, if you want to run via npm globally)

1. Install the package globally:

npm install -g mcp-openapi-schema-explorer

2. Run with your preferred spec (example):

mcp-openapi-schema-explorer <path-or-url-to-spec> --output-format yaml

Option B: Local development / installation (cloning repository and building locally)

1. Clone the repository and install dependencies:

git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
cd mcp-openapi-schema-explorer
npm install

2. Build the project (if a build step exists):

npm run build

3. Run from the local build (example):

node dist/server.js <path-or-url-to-spec> --output-format yaml

Option C: Docker usage (recommended for MCP clients integration)

1. Pull and run the Docker image with a remote spec:

docker run --rm -i kadykov/mcp-openapi-schema-explorer:latest <remote-url-to-spec>

2. Or mount a local file into the container:

docker run --rm -i -v /full/host/path/to/spec.yaml:/spec/api.yaml kadykov/mcp-openapi-schema-explorer:latest /spec/api.yaml --output-format yaml

If you are configuring an MCP client, use one of the provided configuration examples (npx or Docker) to connect to the server with your chosen spec.

Notes and tips:

• The server provides resource templates for dynamic, on-demand access to parts of the OpenAPI/Swagger spec (e.g., paths, components) without pre-enumerating every possible resource.
• Swagger v2.0 specs are automatically converted to OpenAPI v3.0 upon loading.
• When using npx, you can omit --output-format to default to json; supported options include json, yaml, json-minified.
• If you run via Docker with a local file, ensure the host path is absolute and correctly mounted, and the container path matches the spec path you provide inside the container.
• Clients should rely on the template endpoints rather than listing all resources; this scales well for very large specifications.
• Keeping the server up to date (via latest tag) helps ensure compatibility with newer MCP clients and spec features.