Skip to content
Back to search

openapi-mcp

Dockerized MCP Server to allow your AI agent to access any API with existing api docs

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ckanthony--openapi-mcp/badge.svg)](/listings/ckanthony--openapi-mcp)

HTML

<a href="/listings/ckanthony--openapi-mcp"><img src="/api/listings/ckanthony--openapi-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Docker

The recommended way to run this tool is via [Docker](https://hub.docker.com/r/ckanthony/openapi-mcp).

Using the Pre-built Docker Hub Image (Recommended)

Alternatively, you can use the pre-built image available on [Docker Hub](https://hub.docker.com/r/ckanthony/openapi-mcp).

1. **Pull the Image:** ```bash docker pull ckanthony/openapi-mcp:latest ``` 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:** ```bash # Navigate to the repository root cd openapi-mcp # Build the Docker image (tag it as you like, e.g., openapi-mcp:latest) docker build -t openapi-mcp:latest . ```

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). ```bash docker run -p 8080:8080 --rm \\ -v $(pwd)/my-api:/app/spec \\ --env-file $(pwd)/my-api/.env \\ openapi-mcp:latest \\ --spec /app/spec/openapi.json \\ --api-key-env API_KEY \\ --api-key-name X-API-Key \\ --api-key-loc header ``` *(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:** ```bash docker run -p 8080:8080 --rm \\ -e SOME_API_KEY="your_actual_key" \\ openapi-mcp:latest \\ --spec https://petstore.swagger.io/v2/swagger.json \\ --api-key-env SOME_API_KEY \\ --api-key-name api_key \\ --api-key-loc header ```

* **Key Docker Run Options:** * `-p <host_port>:8080`: Map a port on your host to the container's default port 8080. * `--rm`: Automatically remove the container when it exits. * `-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`. * `--env-file <path_to_host_env_file>`: Load environment variables from a local file (for API keys, etc.). Path is on the host. * `-e <VAR_NAME>="<value>"`: Pass a single environment variable directly. * `openapi-mcp:latest`: The name of the image you built locally. * `--spec ...`: **Required.** Path to the spec file *inside the container* (e.g., `/app/spec/openapi.json`) or a public URL. * `--port 8080`: (Optional) Change the internal port the server listens on (must match the container port in `-p`). * `--api-key-env`, `--api-key-name`, `--api-key-loc`: Required if the target API needs an API key. * (See `--help` for all command-line options by running `docker run --rm openapi-mcp:latest --help`)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 213 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.