OpenAPI Schema Server

OpenAPI Schema Server

What is OpenAPI Schema Server about?

Provides a Model Context Protocol (MCP) server that loads an OpenAPI JSON or YAML file and offers LLM‑friendly endpoints for querying the API definition. The server returns information in YAML format, which is easier for language models to parse.

How to use OpenAPI Schema Server?

Command‑line

# default openapi.yaml in the current folder
npx -y mcp-openapi-schema

# specify a schema file (relative path)
npx -y mcp-openapi-schema ../petstore.json

# specify a schema file (absolute path)
npx -y mcp-openapi-schema /absolute/path/to/api-spec.yaml

# show help
npx -y mcp-openapi-schema --help

Claude Desktop integration – add an entry to claude_desktop_config.json with the command and arguments shown above.

Claude Code integration – register the server via the claude mcp add command, then query the API through natural‑language prompts.

Key features of OpenAPI Schema Server

• Loads any OpenAPI file (JSON/YAML) via a single CLI argument
• list-endpoints – returns all paths and HTTP methods with summaries
• get-endpoint – detailed view of a specific operation, including parameters and responses
• get-request-body / get-response-schema – fetches request and response models
• list-components / get-component – inspects reusable schemas, parameters, responses, etc.
• list-security-schemes – enumerates authentication mechanisms
• get-examples – provides example payloads for endpoints or components
• search-schema – full‑text search across the specification
• YAML output for better LLM comprehension

Use cases of OpenAPI Schema Server

• LLM‑assisted API documentation – let Claude or other models answer questions about an API without manual reading of the spec.
• Automated code generation assistance – retrieve request/response schemas to help LLMs produce correct request bodies.
• Rapid API exploration – developers can query endpoints, parameters, and examples directly from their editor/CLI.
• Security auditing – list and examine security schemes programmatically.
• Cross‑API comparison – load multiple specs in different MCP servers and query them side by side.

FAQ

Q: Do I need to install anything globally? A: No. The server runs via npx, which fetches the package on demand.

Q: Which OpenAPI versions are supported? A: Any version that can be parsed by the underlying library (typically 3.0.x and 3.1.x).

Q: Can I run the server with a custom port? A: The package uses the default MCP port conventions; custom ports can be set via environment variables if needed (not documented in the README).

Q: How does the server return data? A: Responses are serialized in YAML to make them easier for LLMs to read.

Q: Is the server compatible with Claude Desktop and Claude Code? A: Yes – the README includes configuration snippets for both integrations.

OpenAPI Schema Model Context Protocol Server

A Model Context Protocol (MCP) server that exposes OpenAPI schema information to Large Language Models (LLMs) like Claude. This server allows an LLM to explore and understand OpenAPI specifications through a set of specialized tools.

Features

• Load any OpenAPI schema file (JSON or YAML) specified via command line argument
• Explore API paths, operations, parameters, and schemas
• View detailed request and response schemas
• Look up component definitions and examples
• Search across the entire API specification
• Get responses in YAML format for better LLM comprehension

Usage

Command Line

Run the MCP server with a specific schema file:

# Use the default openapi.yaml in current directory
npx -y mcp-openapi-schema

# Use a specific schema file (relative path)
npx -y mcp-openapi-schema ../petstore.json

# Use a specific schema file (absolute path)
npx -y mcp-openapi-schema /absolute/path/to/api-spec.yaml

# Show help
npx -y mcp-openapi-schema --help

Claude Desktop Integration

To use this MCP server with Claude Desktop, edit your claude_desktop_config.json configuration file:

{
  "mcpServers": {
    "OpenAPI Schema": {
      "command": "npx",
      "args": ["-y", "mcp-openapi-schema", "/ABSOLUTE/PATH/TO/openapi.yaml"]
    }
  }
}

Location of the configuration file:

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: $env:AppData\Claude\claude_desktop_config.json

Claude Code Integration

To use this MCP server with Claude Code CLI, follow these steps:

1. Add the OpenAPI Schema MCP server to Claude Code

   # Basic syntax
   claude mcp add openapi-schema npx -y mcp-openapi-schema
   
   # Example with specific schema
   claude mcp add petstore-api npx -y mcp-openapi-schema ~/Projects/petstore.yaml
   

2. Verify the MCP server is registered

   # List all configured servers
   claude mcp list
   
   # Get details for your OpenAPI schema server
   claude mcp get openapi-schema
   

3. Remove the server if needed

   claude mcp remove openapi-schema
   

4. Use the tool in Claude Code

   Once configured, you can invoke the tool in your Claude Code session by asking questions about the OpenAPI schema.

Tips:

• Use the -s or --scope flag with project (default) or global to specify where the configuration is stored
• Add multiple MCP servers for different APIs with different names

MCP Tools

The server provides the following tools for LLMs to interact with OpenAPI schemas:

• list-endpoints: Lists all API paths and their HTTP methods with summaries in a nested object structure
• get-endpoint: Gets detailed information about a specific endpoint including parameters and responses
• get-request-body: Gets the request body schema for a specific endpoint and method
• get-response-schema: Gets the response schema for a specific endpoint, method, and status code
• get-path-parameters: Gets the parameters for a specific path
• list-components: Lists all schema components (schemas, responses, parameters, etc.)
• get-component: Gets detailed definition for a specific component
• list-security-schemes: Lists all available security schemes
• get-examples: Gets examples for a specific component or endpoint
• search-schema: Searches across paths, operations, and schemas

Examples

Example queries to try:

What endpoints are available in this API?
Show me the details for the POST /pets endpoint.
What parameters does the GET /pets/{petId} endpoint take?
What is the request body schema for creating a new pet?
What response will I get from the DELETE /pets/{petId} endpoint?
What schemas are defined in this API?
Show me the definition of the Pet schema.
What are the available security schemes for this API?
Are there any example responses for getting a pet by ID?
Search for anything related to "user" in this API.