Openapi Schema

🚀 OpenAPI Model Context Protocol Server

An MCP (Model Context Protocol) server that exposes OpenAPI schema information to large language models (LLMs) such as Claude. This server enables LLMs to explore and understand OpenAPI specifications by providing information through a series of dedicated tools.

✨ Features

• Load any specified OpenAPI schema file (JSON or YAML), which can be specified via command-line arguments.
• Explore API paths, operations, parameters, and schemas.
• View detailed schemas for requests and responses.
• Find component definitions and examples.
• Search across the entire API specification.
• Obtain responses in YAML format for better understanding by LLMs.

📦 Installation

💻 Usage Examples

Basic Usage

This section provides different ways to run the MCP server and configure it with different Claude integrations.

Command Line

Run the MCP server and specify a particular schema file:

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

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

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

# Display help information
npx -y mcp-openapi-schema --help

Claude Desktop Integration

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

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

Configuration file locations:

• 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 a specific schema file
claude mcp add petstore-api npx -y mcp-openapi-schema ~/Projects/petstore.yaml

2. Verify the registered server

# List all configured servers
claude mcp list

# Get detailed information about your OpenAPI schema server
claude mcp get openapi-schema

3. Remove the server if necessary

claude mcp remove openapi-schema

4. Use the tool in Claude Code After configuration, you can call this tool in a Claude Code session by asking questions about the OpenAPI schema.

💡 Usage Tip

• 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 and use different names.

📚 Documentation

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

• list-endpoints: List all API paths, their HTTP methods, and summaries in a nested object structure.
• get-endpoint: Get detailed information about a specific endpoint, including parameters and responses.
• get-request-body: Get the request body schema for a specific endpoint and method.
• get-response-schema: Get the response schema for a specific endpoint, method, and status code.
• get-path-parameters: Get the parameters for a specific path.
• list-components: List all components (e.g., schemas, parameters, etc.).
• get-component: Get detailed information about a specific component.
• list-tags: List all tags.
• get-tag: Get detailed information about a specific tag.

Example Queries

List all endpoints

operation:
  name: list-endpoints
  parameters:
    - name: filter
      type: string
      description: Filter condition (optional)

Get detailed information about a specific endpoint

operation:
  name: get-endpoint
  parameters:
    - name: endpointId
      type: string
      required: true
      description: Endpoint ID

Get the request body schema

operation:
  name: get-request-body
  parameters:
    - name: requestId
      type: string
      required: true
      description: Request ID

Get the response schema

operation:
  name: get-response-schema
  parameters:
    - name: responseId
      type: string
      required: true
      description: Response ID

Example query

curl -X GET "http://localhost:8080/api-docs"