ckanthony/openapi-mcp

**Generate MCP tool definitions directly from a Swagger/OpenAPI specification file.**
OpenAPI-MCP is a dockerized MCP server that reads a swagger.json or openapi.yaml file and generates a corresponding Model Context Protocol (MCP) toolset. This allows MCP-compatible clients like Cursor to interact with APIs described by standard OpenAPI specifications. Now you can enable your AI agent to access any API by simply providing its OpenAPI/Swagger specification - no additional coding required.
Table of Contents
- Why OpenAPI-MCP?
- Features
- Installation
- Using the Pre-built Docker Hub Image (Recommended)
- Building Locally (Optional)
- Running the Weatherbit Example (Step-by-Step)
- Command-Line Options
- Environment Variables
Demo
Run the demo yourself: Running the Weatherbit Example (Step-by-Step)
Why OpenAPI-MCP?
- **Standard Compliance:** Leverage your existing OpenAPI/Swagger documentation.
- **Automatic Tool Generation:** Create MCP tools without manual configuration for each endpoint.
- **Flexible API Key Handling:** Securely manage API key authentication for the proxied API without exposing keys to the MCP client.
- **Local & Remote Specs:** Works with local specification files or remote URLs.
- **Dockerized Tool:** Easily deploy and run as a containerized service with Docker.
Features
- **OpenAPI v2 (Swagger) & v3 Support:** Parses standard specification formats.
- **Schema Generation:** Creates MCP tool schemas from OpenAPI operation parameters and request/response definitions.
- **Secure API Key Management:**
- Injects API keys into requests (header, query, path, cookie) based on command-line configuration.
- Loads API keys directly from flags (--api-key), environment variables (--api-key-env), or .env files located alongside local specs.
- Keeps API keys hidden from the end MCP client (e.g., the AI assistant).
- **Server URL Detection:** Uses server URLs from the spec as the base for tool interactions (can be overridden).
- **Filtering:** Options to include/exclude specific operations or tags (--include-tag, --exclude-tag, --include-op, --exclude-op).
- **Request Header Injection:** Pass custom headers (e.g., for additional auth, tracing) via the REQUEST_HEADERS environment variable.
Installation
Docker
The recommended way to run this tool is via Docker.
Using the Pre-built Docker Hub Image (Recommended)
Alternatively, you can use the pre-built image available on Docker Hub.
1. **Pull the Image:**
2. **Run the Container:**
Follow the docker run examples above, but replace openapi-mcp:latest with ckanthony/openapi-mcp:latest.
Building Locally (Optional)
1. **Build the Docker Image Locally:**
2. **Run the Container:**
You need to provide the OpenAPI specification and any necessary API key configuration when running the container.
* **Example 1: Using a local spec file and .env file:**
- Create a directory (e.g., ./my-api) containing your openapi.json or swagger.yaml.
- If the API requires a key, create a .env file in the *same directory* (e.g., ./my-api/.env) with API_KEY=your_actual_key (replace API_KEY if your --api-key-env flag is different).
*(Adjust --spec, --api-key-env, --api-key-name, --api-key-loc, and -p as needed.)*
* **Example 2: Using a remote spec URL and direct environment variable:**
* **Key Docker Run Options:**
* -p :8080: Map a port on your host to the container's default port 8080.
* --rm: Automatically remove the container when it exits.
* -v : : Mount a local directory containing your spec into the container. Use absolute paths or $(pwd)/.... Common container path: /app/spec.
* --env-file : Load environment variables from a local file (for API keys, etc.). Path is on the host.