MCP OpenAPI Schema Explorer

An MCP (Model Context Protocol) server that provides token-efficient access to OpenAPI (v3.0) and Swagger (v2.0) specifications via MCP Resource Templates.

Project Goal

The primary goal of this project is to allow MCP clients (like Cline or Claude Desktop) to explore the structure and details of large OpenAPI specifications without needing to load the entire file into an LLM's context window. It achieves this by exposing parts of the specification through MCP Resource Templates, which provide parameterized access patterns for read-only data exploration.

This server supports loading specifications from both local file paths and remote HTTP/HTTPS URLs. Swagger v2.0 specifications are automatically converted to OpenAPI v3.0 upon loading.

Note: This server provides resource templates (not pre-enumerated resources). MCP clients access these templates through the resources/templates/list protocol method. For more information about resource templates, see the MCP Resource Templates documentation.

Why MCP Resource Templates?

The Model Context Protocol defines both Resources and Tools.

• Resources: Represent data sources (like files, API responses). They are ideal for read-only access and exploration by MCP clients.
  • Resource Templates: A special type of resource that uses parameterized URIs (e.g., openapi://paths/{path}/{method}), allowing dynamic access without pre-enumerating all possible values.
• Tools: Represent executable actions or functions, often used by LLMs to perform tasks or interact with external systems.

While other MCP servers exist that provide access to OpenAPI specs via Tools, this project specifically focuses on providing access via Resource Templates. This approach is particularly efficient for large APIs because:

• It doesn't require pre-enumerating thousands of potential paths and components
• Clients can discover available resources dynamically using the template patterns
• It provides structured, on-demand access to specific parts of the specification

For more details on MCP clients and their capabilities, see the MCP Client Documentation.

Quick Start Guides by Client

• Claude Code - Anthropic's CLI tool for coding with Claude
• Claude Desktop, Cline, Windsurf - See installation instructions below

Installation

For the recommended usage methods (npx and Docker, described below), no separate installation step is required. Your MCP client will download the package or pull the Docker image automatically based on the configuration you provide.

However, if you prefer or need to install the server explicitly, you have two options:

1. Global Installation: You can install the package globally using npm:

   Terminal

   Copy

   npm install -g mcp-openapi-schema-explorer
   

   See Method 3 below for how to configure your MCP client to use a globally installed server.

2. Local Development/Installation: You can clone the repository and build it locally:

   bash

   Copy

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

   See Method 4 below for how to configure your MCP client to run the server from your local build using node.

Adding the Server to your MCP Client

This server is designed to be run by MCP clients (like Claude Desktop, Windsurf, Cline, etc.). To use it, you add a configuration entry to your client's settings file (often a JSON file). This entry tells the client how to execute the server process (e.g., using npx, docker, or node). The server itself doesn't require separate configuration beyond the command-line arguments specified in the client settings entry.

Below are the common methods for adding the server entry to your client's configuration.

Method 1: npx (Recommended)

Using npx is recommended as it avoids global/local installation and ensures the client uses the latest published version.

Example Client Configuration Entry (npx Method):

Add the following JSON object to the mcpServers section of your MCP client's configuration file. This entry instructs the client on how to run the server using npx:

{
  "mcpServers": {
    "My API Spec (npx)": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-openapi-schema-explorer@latest",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],
      "env": {}
    }
  }
}

Configuration Notes:

• Replace "My API Spec (npx)" with a unique name for this server instance in your client.
• Replace <path-or-url-to-spec> with the absolute local file path or full remote URL of your specification.
• The --output-format is optional (json, yaml, json-minified), defaulting to json.
• To explore multiple specifications, add separate entries in mcpServers, each with a unique name and pointing to a different spec.

Method 2: Docker

You can instruct your MCP client to run the server using the official Docker image: kadykov/mcp-openapi-schema-explorer.

Example Client Configuration Entries (Docker Method):

Add one of the following JSON objects to the mcpServers section of your MCP client's configuration file. These entries instruct the client on how to run the server using docker run:

• Remote URL: Pass the URL directly to docker run.

• Using a Remote URL:

  config.json

  Copy

  {
    "mcpServers": {
      "My API Spec (Docker Remote)": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "kadykov/mcp-openapi-schema-explorer:latest",
          "<remote-url-to-spec>"
        ],
        "env": {}
      }
    }
  }
  

• Using a Local File: (Requires mounting the file into the container)

  config.json

  Copy

  {
    "mcpServers": {
      "My API Spec (Docker Local)": {
        "command": "docker",
        "args": [
          "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"
        ],
        "env": {}
      }
    }
  }
  

  Important: Replace /full/host/path/to/spec.yaml with the correct absolute path on your host machine. The path /spec/api.yaml is the corresponding path inside the container.

Method 3: Global Installation (Less Common)

If you have installed the package globally using npm install -g, you can configure your client to run it directly.

# Run this command once in your terminal
npm install -g mcp-openapi-schema-explorer

Example Client Configuration Entry (Global Install Method):

Add the following entry to your MCP client's configuration file. This assumes the mcp-openapi-schema-explorer command is accessible in the client's execution environment PATH.

{
  "mcpServers": {
    "My API Spec (Global)": {
      "command": "mcp-openapi-schema-explorer",
      "args": ["<path-or-url-to-spec>", "--output-format", "yaml"],
      "env": {}
    }
  }
}

• Ensure the command (mcp-openapi-schema-explorer) is accessible in the PATH environment variable used by your MCP client.

Method 4: Local Development/Installation

This method is useful if you have cloned the repository locally for development or to run a modified version.

Setup Steps (Run once in your terminal):

1. Clone the repository: git clone https://github.com/kadykov/mcp-openapi-schema-explorer.git
2. Navigate into the directory: cd mcp-openapi-schema-explorer
3. Install dependencies: npm install
4. Build the project: npm run build (or just build)

Example Client Configuration Entry (Local Development Method):

Add the following entry to your MCP client's configuration file. This instructs the client to run the locally built server using node.

{
  "mcpServers": {
    "My API Spec (Local Dev)": {
      "command": "node",
      "args": [
        "/full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js",
        "<path-or-url-to-spec>",
        "--output-format",
        "yaml"
      ],

      "env": {}
    }
  }
}

Important: Replace /full/path/to/cloned/mcp-openapi-schema-explorer/dist/src/index.js with the correct absolute path to the built index.js file in your cloned repository.

Features