openapi-mcp

Point it at an OpenAPI 3.x document and get an MCP server that exposes the API's endpoints as typed, validated tools for Claude or any MCP client.

pip install -e .

OPENAPI_SPEC=./openapi.json \
OPENAPI_AUTH_KIND=bearer OPENAPI_AUTH_VALUE=$TOKEN \
python -m openapi_mcp

Each operation in the spec becomes one tool. Parameter schemas come from the spec itself, so the model sees real types and required fields instead of a free-text prompt.

Design choices

• The model cannot call the API wrongly. Every parameter carries its real JSON Schema, required fields are marked required, and unknown arguments are rejected rather than silently dropped. A tool that quietly ignores an argument is worse than one that errors, because the model believes it worked.

• Errors are written for a model, not a human with a debugger. An AI client cannot read a stack trace, but it can read "404, the user id does not exist". Failures come back as short factual sentences naming the status and the API's own message. Secrets never appear in them.

• The whole test suite runs offline. Transport is injected behind a Protocol, so tests run against a fake with no network and no cassettes. PYTHONPATH=src python -m pytest tests/ -q

• Credentials are environment-only. Command line arguments end up in shell history and in ps output; environment variables do not.

Auth

OPENAPI_AUTH_KIND is one of none, bearer, header, or query, with OPENAPI_AUTH_VALUE and (for header/query) OPENAPI_AUTH_NAME.

Scope, stated plainly

This handles the OpenAPI subset that real-world REST APIs actually use: local $ref, path, query and header parameters, JSON request bodies. It does not resolve remote or URL $ref, and it does not attempt full JSON Schema composition (allOf and oneOf pass through as-is). Unsupported input raises, it never silently degrades. Cookie parameters are parsed but rejected at tool build time, because sending cookies on a machine-driven call is a footgun.

Claude Desktop config

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["-m", "openapi_mcp"],
      "env": {
        "OPENAPI_SPEC": "/path/to/openapi.json",
        "OPENAPI_AUTH_KIND": "bearer",
        "OPENAPI_AUTH_VALUE": "your-test-token"
      }
    }
  }
}

MIT licensed. Built and maintained by lumenpike.