mcp-openapi-schema

This MCP server exposes an OpenAPI schema model to LLMs, enabling exploration and understanding of an OpenAPI specification in a structured, tool-based way. It loads a provided OpenAPI file (JSON or YAML) and offers a suite of tools that let you list endpoints, inspect endpoint details, view request/response schemas, inspect components, and search across the spec. The result is a more navigable, human-readable view of an API, with responses available in YAML format to improve readability for language models.

To use it, provide the path to your OpenAPI file when starting the server via npx (as shown in the command examples). Once the server is running, you can invoke the built-in tools such as list-endpoints to get a structured overview of all paths and HTTP methods, get-endpoint to dive into a specific operation, get-request-body or get-response-schema to inspect payload schemas, and list-components or get-component to explore reusable definitions. The search-schema tool lets you look for specific terms across paths, operations, and schemas, making it easy to locate relevant parts of the API spec. All tool outputs are designed to be precise and interpretable by LLMs, with YAML-formatted responses where helpful.

For Claude users, you can configure Claude Desktop or Claude Code to point to the MCP server by using the provided command pattern, specifying the OpenAPI YAML file path. This enables seamless querying within Claude workflows, allowing questions like "What are the available endpoints for creating a pet?" or "Show me the Pet schema definition."

Prerequisites:

• Node.js and npm installed on your system
• Internet access to fetch the MCP server package via npx

Installation steps:

1. Ensure Node.js is installed. You can verify with: node -v npm -v

2. Install and run the MCP server using npx with your OpenAPI file path. Replace <PATH_TO_OPENAPI_YAML> with the actual path to your OpenAPI spec (JSON or YAML):

   npx -y mcp-openapi-schema <PATH_TO_OPENAPI_YAML>

3. If you want to pin the server to a specific OpenAPI file for repeated runs, you can reuse the command or create a small script that calls the same npx command with your file path.

4. (Optional) If you prefer to install locally, you can clone the repository and install dependencies, then run the server according to its package.json scripts. Follow the repository's own instructions if provided.

5. For Claude integration, use the provided configuration pattern to register the MCP server with Claude tools (see usage section for examples for Desktop and Code).

Tips and considerations:

• You can pass different OpenAPI files to explore multiple APIs. Use a descriptive server name when configuring Claude to avoid confusion.
• The server returns YAML-formatted outputs for many tools to improve readability for LLMs.
• If you encounter file path issues, ensure the path is accessible from the environment where the MCP server runs (absolute paths tend to be more reliable).
• When testing in Claude Code, you can add multiple MCP servers to compare schemas side-by-side.
• Common issues include invalid OpenAPI syntax or unsupported OpenAPI features; validate your schema with an OpenAPI validator before loading if you see unexpected tool behavior.