OpenApiMcpServer

# 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:** ```json { "method": "GET", "path": "/users/123" } ``` **Output:** ```json { "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:** ```json [ { "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: ```bash npm install -g github:Hagelslag77/OpenApiMcpServer ``` Install a specific release: ```bash npm install -g github:Hagelslag77/OpenApiMcpServer#v1.0.0 ``` npm will automatically build the project during installation. ### From Source ```bash 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: ```bash node dist/index.js --spec ./openapi.yaml # or OPENAPI_SPEC_PATH=./openapi.yaml node dist/index.js ``` ### MCP Inspector ```bash npx @modelcontextprotocol/inspector node dist/index.js --spec ./openapi.yaml ``` ### Claude Code Register the server with Claude Code using the `claude mcp add` command: ```bash 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): ```bash claude mcp add --scope project openapi-mcp -- node /absolute/path/to/dist/index.js --spec ./openapi.yaml ``` Verify the server is registered: ```bash claude mcp list ``` ### Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "openapi": { "command": "node", "args": ["/absolute/path/to/dist/index.js", "--spec", "/absolute/path/to/openapi.yaml"] } } } ``` ## Development ```bash npm test # build + run unit tests npm run build # compile TypeScript to dist/ ```