Openapi MCP

1# OpenAPI-MCP: Dockerized MCP Server to allow your AI agent to access any API with existing api docs
2 
3[![Go Reference](https://pkg.go.dev/badge/github.com/ckanthony/openapi-mcp.svg)](https://pkg.go.dev/github.com/ckanthony/openapi-mcp)
4[![CI](https://github.com/ckanthony/openapi-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ckanthony/openapi-mcp/actions/workflows/ci.yml)
5[![codecov](https://codecov.io/gh/ckanthony/openapi-mcp/branch/main/graph/badge.svg)](https://codecov.io/gh/ckanthony/openapi-mcp)
6![](https://badge.mcpx.dev?type=dev 'MCP Dev')
7 
8[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/ckanthony/openapi-mcp)](https://archestra.ai/mcp-catalog/ckanthony__openapi-mcp)
9 
10![openapi-mcp logo](openapi-mcp.png)
11 
12**Generate MCP tool definitions directly from a Swagger/OpenAPI specification file.**
13 
14OpenAPI-MCP is a dockerized MCP server that reads a `swagger.json` or `openapi.yaml` file and generates a corresponding [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) toolset. This allows MCP-compatible clients like [Cursor](https://cursor.sh/) 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.
15 
16## Table of Contents
17 
18-   [Why OpenAPI-MCP?](#why-openapi-mcp)
19-   [Features](#features)
20-   [Installation](#installation)
21    -   [Using the Pre-built Docker Hub Image (Recommended)](#using-the-pre-built-docker-hub-image-recommended)
22    -   [Building Locally (Optional)](#building-locally-optional)
23-   [Running the Weatherbit Example (Step-by-Step)](#running-the-weatherbit-example-step-by-step)
24-   [Command-Line Options](#command-line-options)
25    -   [Environment Variables](#environment-variables)
26 
27## Demo
28 
29Run the demo yourself: [Running the Weatherbit Example (Step-by-Step)](#running-the-weatherbit-example-step-by-step)
30 
31![demo](https://github.com/user-attachments/assets/4d457137-5da4-422a-b323-afd4b175bd56)
32 
33## Why OpenAPI-MCP?
34 
35-   **Standard Compliance:** Leverage your existing OpenAPI/Swagger documentation.
36-   **Automatic Tool Generation:** Create MCP tools without manual configuration for each endpoint.
37-   **Flexible API Key Handling:** Securely manage API key authentication for the proxied API without exposing keys to the MCP client.
38-   **Local & Remote Specs:** Works with local specification files or remote URLs.
39-   **Dockerized Tool:** Easily deploy and run as a containerized service with Docker.
40 
41## Features
42 
43-   **OpenAPI v2 (Swagger) & v3 Support:** Parses standard specification formats.
44-   **Schema Generation:** Creates MCP tool schemas from OpenAPI operation parameters and request/response definitions.
45-   **Secure API Key Management:**
46    -   Injects API keys into requests (`header`, `query`, `path`, `cookie`) based on command-line configuration.
47        -   Loads API keys directly from flags (`--api-key`), environment variables (`--api-key-env`), or `.env` files located alongside local specs.
48        -   Keeps API keys hidden from the end MCP client (e.g., the AI assistant).
49-   **Server URL Detection:** Uses server URLs from the spec as the base for tool interactions (can be overridden).
50-   **Filtering:** Options to include/exclude specific operations or tags (`--include-tag`, `--exclude-tag`, `--include-op`, `--exclude-op`).
51-   **Request Header Injection:** Pass custom headers (e.g., for additional auth, tracing) via the `REQUEST_HEADERS` environment variable.
52 
53## Installation
54 
55### Docker
56 
57The recommended way to run this tool is via [Docker](https://hub.docker.com/r/ckanthony/openapi-mcp).
58 
59#### Using the Pre-built Docker Hub Image (Recommended)
60 
61Alternatively, you can use the pre-built image available on [Docker Hub](https://hub.docker.com/r/ckanthony/openapi-mcp).
62 
631.  **Pull the Image:**
64    ```bash
65    docker pull ckanthony/openapi-mcp:latest
66    ```
672.  **Run the Container:**
68    Follow the `docker run` examples above, but replace `openapi-mcp:latest` with `ckanthony/openapi-mcp:latest`.
69 
70#### Building Locally (Optional)
71 
721.  **Build the Docker Image Locally:**
73    ```bash
74    # Navigate to the repository root
75    cd openapi-mcp
76    # Build the Docker image (tag it as you like, e.g., openapi-mcp:latest)
77    docker build -t openapi-mcp:latest .
78    ```
79 
802.  **Run the Container:**
81    You need to provide the OpenAPI specification and any necessary API key configuration when running the container.
82 
83    *   **Example 1: Using a local spec file and `.env` file:**
84        -   Create a directory (e.g., `./my-api`) containing your `openapi.json` or `swagger.yaml`.
85        -   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).
86        ```bash
87        docker run -p 8080:8080 --rm \\
88            -v $(pwd)/my-api:/app/spec \\
89            --env-file $(pwd)/my-api/.env \\
90            openapi-mcp:latest \\
91            --spec /app/spec/openapi.json \\
92            --api-key-env API_KEY \\
93            --api-key-name X-API-Key \\
94            --api-key-loc header
95        ```
96        *(Adjust `--spec`, `--api-key-env`, `--api-key-name`, `--api-key-loc`, and `-p` as needed.)*
97 
98    *   **Example 2: Using a remote spec URL and direct environment variable:**
99        ```bash
100        docker run -p 8080:8080 --rm \\
101            -e SOME_API_KEY="your_actual_key" \\
102            openapi-mcp:latest \\
103            --spec https://petstore.swagger.io/v2/swagger.json \\
104            --api-key-env SOME_API_KEY \\
105            --api-key-name api_key \\
106            --api-key-loc header
107        ```
108 
109    *   **Key Docker Run Options:**
110        *   `-p <host_port>:8080`: Map a port on your host to the container's default port 8080.
111        *   `--rm`: Automatically remove the container when it exits.
112        *   `-v <host_path>:<container_path>`: Mount a local directory containing your spec into the container. Use absolute paths or `$(pwd)/...`. Common container path: `/app/spec`.
113        *   `--env-file <path_to_host_env_file>`: Load environment variables from a local file (for API keys, etc.). Path is on the host.
114        *   `-e <VAR_NAME>="<value>"`: Pass a single environment variable directly.
115        *   `openapi-mcp:latest`: The name of the image you built locally.
116        *   `--spec ...`: **Required.** Path to the spec file *inside the container* (e.g., `/app/spec/openapi.json`) or a public URL.
117        *   `--port 8080`: (Optional) Change the internal port the server listens on (must match the container port in `-p`).
118        *   `--api-key-env`, `--api-key-name`, `--api-key-loc`: Required if the target API needs an API key.
119        *   (See `--help` for all command-line options by running `docker run --rm openapi-mcp:latest --help`)
120 
121 
122## Running the Weatherbit Example (Step-by-Step)
123 
124This repository includes an example using the [Weatherbit API](https://www.weatherbit.io/). Here's how to run it using the public Docker image:
125 
1261.  **Find OpenAPI Specs (Optional Knowledge):**
127    Many public APIs have their OpenAPI/Swagger specifications available online. A great resource for discovering them is [APIs.guru](https://apis.guru/). The Weatherbit specification used in this example (`weatherbitio-swagger.json`) was sourced from there.
128 
1292.  **Get a Weatherbit API Key:**
130    *   Go to [Weatherbit.io](https://www.weatherbit.io/) and sign up for an account (they offer a free tier).
131    *   Find your API key in your Weatherbit account dashboard.
132 
1333.  **Clone this Repository:**
134    You need the example files from this repository.
135    ```bash
136    git clone https://github.com/ckanthony/openapi-mcp.git
137    cd openapi-mcp
138    ```
139 
1404.  **Prepare Environment File:**
141    *   Navigate to the example directory: `cd example/weather`
142    *   Copy the example environment file: `cp .env.example .env`
143    *   Edit the new `.env` file and replace `YOUR_WEATHERBIT_API_KEY_HERE` with the actual API key you obtained from Weatherbit.
144 
1455.  **Run the Docker Container:**
146    From the `openapi-mcp` **root directory** (the one containing the `example` folder), run the following command:
147    ```bash
148    docker run -p 8080:8080 --rm \\
149        -v $(pwd)/example/weather:/app/spec \\
150        --env-file $(pwd)/example/weather/.env \\
151        ckanthony/openapi-mcp:latest \\
152        --spec /app/spec/weatherbitio-swagger.json \\
153        --api-key-env API_KEY \\
154        --api-key-name key \\
155        --api-key-loc query
156    ```
157    *   `-v $(pwd)/example/weather:/app/spec`: Mounts the local `example/weather` directory (containing the spec and `.env` file) to `/app/spec` inside the container.
158    *   `--env-file $(pwd)/example/weather/.env`: Tells Docker to load environment variables (specifically `API_KEY`) from your `.env` file.
159    *   `ckanthony/openapi-mcp:latest`: Uses the public Docker image.
160    *   `--spec /app/spec/weatherbitio-swagger.json`: Points to the spec file inside the container.
161    *   The `--api-key-*` flags configure how the tool should inject the API key (read from the `API_KEY` env var, named `key`, placed in the `query` string).
162 
1636.  **Access the MCP Server:**
164    The MCP server should now be running and accessible at `http://localhost:8080` for compatible clients.
165 
166**Using Docker Compose (Example):**
167 
168A `docker-compose.yml` file is provided in the `example/` directory to demonstrate running the Weatherbit API example using the *locally built* image.
169 
1701.  **Prepare Environment File:** Copy `example/weather/.env.example` to `example/weather/.env` and add your actual Weatherbit API key:
171    ```dotenv
172    # example/weather/.env
173    API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY
174    ```
175 
1762.  **Run with Docker Compose:** Navigate to the `example` directory and run:
177    ```bash
178    cd example
179    # This builds the image locally based on ../Dockerfile
180    # It does NOT use the public Docker Hub image
181    docker-compose up --build
182    ```
183    *   `--build`: Forces Docker Compose to build the image using the `Dockerfile` in the project root before starting the service.
184    *   Compose will read `example/docker-compose.yml`, build the image, mount `./weather`, read `./weather/.env`, and start the `openapi-mcp` container with the specified command-line arguments.
185    *   The MCP server will be available at `http://localhost:8080`.
186 
1873.  **Stop the service:** Press `Ctrl+C` in the terminal where Compose is running, or run `docker-compose down` from the `example` directory in another terminal.
188 
189## Command-Line Options
190 
191The `openapi-mcp` command accepts the following flags:
192 
193| Flag                 | Description                                                                                                         | Type          | Default                          |
194|----------------------|---------------------------------------------------------------------------------------------------------------------|---------------|----------------------------------|
195| `--spec`             | **Required.** Path or URL to the OpenAPI specification file.                                                          | `string`      | (none)                           |
196| `--port`             | Port to run the MCP server on.                                                                                      | `int`         | `8080`                           |
197| `--api-key`          | Direct API key value (use `--api-key-env` or `.env` file instead for security).                                       | `string`      | (none)                           |
198| `--api-key-env`      | Environment variable name containing the API key. If spec is local, also checks `.env` file in the spec's directory. | `string`      | (none)                           |
199| `--api-key-name`     | **Required if key used.** Name of the API key parameter (header, query, path, or cookie name).                       | `string`      | (none)                           |
200| `--api-key-loc`      | **Required if key used.** Location of API key: `header`, `query`, `path`, or `cookie`.                              | `string`      | (none)                           |
201| `--include-tag`      | Tag to include (can be repeated). If include flags are used, only included items are exposed.                       | `string slice`| (none)                           |
202| `--exclude-tag`      | Tag to exclude (can be repeated). Exclusions apply after inclusions.                                                | `string slice`| (none)                           |
203| `--include-op`       | Operation ID to include (can be repeated).                                                                          | `string slice`| (none)                           |
204| `--exclude-op`       | Operation ID to exclude (can be repeated).                                                                          | `string slice`| (none)                           |
205| `--base-url`         | Manually override the target API server base URL detected from the spec.                                              | `string`      | (none)                           |
206| `--name`             | Default name for the generated MCP toolset (used if spec has no title).                                             | `string`      | "OpenAPI-MCP Tools"            |
207| `--desc`             | Default description for the generated MCP toolset (used if spec has no description).                                | `string`      | "Tools generated from OpenAPI spec" |
208 
209**Note:** You can get this list by running the tool with the `--help` flag (e.g., `docker run --rm ckanthony/openapi-mcp:latest --help`).
210 
211### Environment Variables
212 
213*   `REQUEST_HEADERS`: Set this environment variable to a JSON string (e.g., `'{"X-Custom": "Value"}'`) to add custom headers to *all* outgoing requests to the target API.
214