OpenAPI MCP Server

An MCP (Model Context Protocol) server that loads an OpenAPI YAML/JSON specification and exposes it as queryable tools for AI agents. Agents can look up REST route specifications by HTTP method and path, getting back the full resolved operation object with all $ref schemas inlined.

Tools

`lookup_operation`

Returns the full resolved OpenAPI operation for a given HTTP method and path.

Supports parameterized paths: passing /users/123 will match /users/{id} in the spec
Resolves all $ref schemas inline so the agent gets complete type information
Returns the matched path template and any captured path parameters

Input:

{ "method": "GET", "path": "/users/123" }

Output:

{
  "method": "GET",
  "pathTemplate": "/users/{id}",
  "capturedParams": { "id": "123" },
  "operation": {
    "operationId": "getUserById",
    "summary": "Get a user by ID",
    "parameters": [...],
    "responses": { ... }
  }
}

`list_routes`

Lists all HTTP routes defined in the loaded spec. Useful for discovering available operations before calling lookup_operation.

Output:

[
  { "method": "GET",  "path": "/users",     "operationId": "listUsers",   "summary": "List all users" },
  { "method": "POST", "path": "/users",     "operationId": "createUser",  "summary": "Create a user" },
  { "method": "GET",  "path": "/users/{id}","operationId": "getUserById", "summary": "Get a user by ID" }
]

Installation

From GitHub

Install the latest version:

npm install -g github:Hagelslag77/OpenApiMcpServer

Install a specific release:

npm install -g github:Hagelslag77/OpenApiMcpServer#v1.0.0

npm will automatically build the project during installation.

From Source

git clone https://github.com/Hagelslag77/OpenApiMcpServer.git
cd OpenApiMcpServer
npm install
npm run build

Usage

CLI

Pass the spec file via --spec argument or the OPENAPI_SPEC_PATH environment variable:

node dist/index.js --spec ./openapi.yaml
# or
OPENAPI_SPEC_PATH=./openapi.yaml node dist/index.js

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js --spec ./openapi.yaml

Claude Code

claude mcp add openapi-mcp -- node /absolute/path/to/dist/index.js --spec /absolute/path/to/openapi.yaml

To share the configuration with your team (stored in .mcp.json at the repo root):

claude mcp add --scope project openapi-mcp -- node /absolute/path/to/dist/index.js --spec ./openapi.yaml

Verify the server is registered:

claude mcp list

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openapi": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js", "--spec", "/absolute/path/to/openapi.yaml"]
    }
  }
}

Development

npm test       # build + run unit tests
npm run build  # compile TypeScript to dist/

MCP Servers