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 AP
Add this skill
npx mdskills install ckanthony/openapi-mcpGenerates MCP tools from OpenAPI specs with strong documentation and Docker setup
1# OpenAPI-MCP: Dockerized MCP Server to allow your AI agent to access any API with existing api docs23[](https://pkg.go.dev/github.com/ckanthony/openapi-mcp)4[](https://github.com/ckanthony/openapi-mcp/actions/workflows/ci.yml)5[](https://codecov.io/gh/ckanthony/openapi-mcp)678[](https://archestra.ai/mcp-catalog/ckanthony__openapi-mcp)9101112**Generate MCP tool definitions directly from a Swagger/OpenAPI specification file.**1314OpenAPI-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.1516## Table of Contents1718- [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)2627## Demo2829Run the demo yourself: [Running the Weatherbit Example (Step-by-Step)](#running-the-weatherbit-example-step-by-step)30313233## Why OpenAPI-MCP?3435- **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.4041## Features4243- **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.5253## Installation5455### Docker5657The recommended way to run this tool is via [Docker](https://hub.docker.com/r/ckanthony/openapi-mcp).5859#### Using the Pre-built Docker Hub Image (Recommended)6061Alternatively, you can use the pre-built image available on [Docker Hub](https://hub.docker.com/r/ckanthony/openapi-mcp).62631. **Pull the Image:**64 ```bash65 docker pull ckanthony/openapi-mcp:latest66 ```672. **Run the Container:**68 Follow the `docker run` examples above, but replace `openapi-mcp:latest` with `ckanthony/openapi-mcp:latest`.6970#### Building Locally (Optional)71721. **Build the Docker Image Locally:**73 ```bash74 # Navigate to the repository root75 cd openapi-mcp76 # Build the Docker image (tag it as you like, e.g., openapi-mcp:latest)77 docker build -t openapi-mcp:latest .78 ```79802. **Run the Container:**81 You need to provide the OpenAPI specification and any necessary API key configuration when running the container.8283 * **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 ```bash87 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 header95 ```96 *(Adjust `--spec`, `--api-key-env`, `--api-key-name`, `--api-key-loc`, and `-p` as needed.)*9798 * **Example 2: Using a remote spec URL and direct environment variable:**99 ```bash100 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 header107 ```108109 * **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`)120121122## Running the Weatherbit Example (Step-by-Step)123124This repository includes an example using the [Weatherbit API](https://www.weatherbit.io/). Here's how to run it using the public Docker image:1251261. **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.1281292. **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.1321333. **Clone this Repository:**134 You need the example files from this repository.135 ```bash136 git clone https://github.com/ckanthony/openapi-mcp.git137 cd openapi-mcp138 ```1391404. **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.1441455. **Run the Docker Container:**146 From the `openapi-mcp` **root directory** (the one containing the `example` folder), run the following command:147 ```bash148 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 query156 ```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).1621636. **Access the MCP Server:**164 The MCP server should now be running and accessible at `http://localhost:8080` for compatible clients.165166**Using Docker Compose (Example):**167168A `docker-compose.yml` file is provided in the `example/` directory to demonstrate running the Weatherbit API example using the *locally built* image.1691701. **Prepare Environment File:** Copy `example/weather/.env.example` to `example/weather/.env` and add your actual Weatherbit API key:171 ```dotenv172 # example/weather/.env173 API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY174 ```1751762. **Run with Docker Compose:** Navigate to the `example` directory and run:177 ```bash178 cd example179 # This builds the image locally based on ../Dockerfile180 # It does NOT use the public Docker Hub image181 docker-compose up --build182 ```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`.1861873. **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.188189## Command-Line Options190191The `openapi-mcp` command accepts the following flags:192193| 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" |208209**Note:** You can get this list by running the tool with the `--help` flag (e.g., `docker run --rm ckanthony/openapi-mcp:latest --help`).210211### Environment Variables212213* `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
Full transparency — inspect the skill content before installing.