openapi-spec-mcp-serve

An MCP (Model Context Protocol) server for reading, writing, and managing OpenAPI specification files. Connect it to Claude Desktop, Claude Code, or any MCP-compatible client to let AI assistants directly create and edit your openapi.yml.

Quick Start

npx openapi-spec-mcp-serve

Features

• Read & write the full spec in YAML or JSON
• Manage paths — add, get, update, delete individual endpoints and HTTP methods
• Manage schemas — add, update, delete reusable component schemas
• Validate your spec against the OpenAPI 3.x standard before every write
• Auto-backup — saves openapi.yml.bak before every destructive operation
• Safe by default — rejects writes that would produce an invalid spec

Tools

| Tool | Description | |---|---| | initialize_spec | Create a new empty OpenAPI 3.1.0 spec | | read_spec | Read the full spec (YAML or JSON) | | write_spec | Overwrite the entire spec | | validate_spec | Validate against OpenAPI 3.x standard | | update_info | Update title, version, description, contact, license | | add_server | Add a server URL | | list_paths | List all paths and methods (filterable by method or tag) | | get_path | Get a specific path or operation | | add_path | Add a new endpoint | | update_path | Merge updates into an existing operation | | delete_path | Delete a path or single method | | list_schemas | List all component schemas | | get_schema | Get a specific schema | | add_schema | Add a reusable schema to components/schemas | | update_schema | Merge updates into an existing schema | | delete_schema | Remove a schema |

Installation

npx openapi-spec-mcp-serve

Or install globally:

npm install -g openapi-spec-mcp-serve
openapi-spec-mcp-serve

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "openapi-spec-manager": {
      "command": "npx",
      "args": ["openapi-spec-mcp-serve"],
      "env": {
        "OPENAPI_FILE_PATH": "/absolute/path/to/your/openapi.yml"
      }
    }
  }
}

Claude Code

claude mcp add openapi-spec-manager \
  -e OPENAPI_FILE_PATH=/path/to/openapi.yml \
  -- npx openapi-spec-mcp-serve

Environment Variables

| Variable | Default | Description | |---|---|---| | OPENAPI_FILE_PATH | ./openapi.yml | Path to the OpenAPI spec file to manage |

Example Prompts

Once connected to Claude, you can say:

• "Initialize a new OpenAPI spec for a Users API v1.0"
• "Add a POST /users endpoint that creates a user with name and email"
• "Add a User schema to components with id, email, and name fields"
• "List all my API endpoints"
• "Update the GET /users description to mention pagination"
• "Validate my spec and fix any errors"
• "Add https://api.example.com/v1 as the production server"

Development

npm run dev   # watch mode (tsc --watch)
npm run build # production build

Project Structure

src/
├── index.ts          # MCP server entry point & tool registration
├── lib/
│   ├── types.ts      # Shared TypeScript types & result helpers
│   ├── parser.ts     # YAML read/write/backup helpers
│   └── validator.ts  # OpenAPI spec validation via swagger-parser
└── tools/
    ├── read.ts       # read_spec
    ├── write.ts      # write_spec, initialize_spec, update_info, add_server
    ├── paths.ts      # list/get/add/update/delete paths
    ├── schemas.ts    # list/get/add/update/delete schemas
    └── validate.ts   # validate_spec