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

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
• Running the Weatherbit Example (Step-by-Step)
• Command-Line Options

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:
• 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:

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:

# 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.

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.)*

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

Running the Weatherbit Example (Step-by-Step)

This repository includes an example using the Weatherbit API. Here's how to run it using the public Docker image:

1. Find OpenAPI Specs (Optional Knowledge):

Many public APIs have their OpenAPI/Swagger specifications available online. A great resource for discovering them is APIs.guru. The Weatherbit specification used in this example (`weatherbitio-swagger.json`) was sourced from there.

2. Get a Weatherbit API Key:

3. Clone this Repository:

You need the example files from this repository.

git clone https://github.com/ckanthony/openapi-mcp.git
    cd openapi-mcp

4. Prepare Environment File:

5. Run the Docker Container:

From the `openapi-mcp` root directory (the one containing the `example` folder), run the following command:

docker run -p 8080:8080 --rm \\
        -v $(pwd)/example/weather:/app/spec \\
        --env-file $(pwd)/example/weather/.env \\
        ckanthony/openapi-mcp:latest \\
        --spec /app/spec/weatherbitio-swagger.json \\
        --api-key-env API_KEY \\
        --api-key-name key \\
        --api-key-loc query

6. Access the MCP Server:

The MCP server should now be running and accessible at `http://localhost:8080` for compatible clients.

Using Docker Compose (Example):

A `docker-compose.yml` file is provided in the `example/` directory to demonstrate running the Weatherbit API example using the *locally built* image.

1. Prepare Environment File: Copy `example/weather/.env.example` to `example/weather/.env` and add your actual Weatherbit API key:

# example/weather/.env
    API_KEY=YOUR_ACTUAL_WEATHERBIT_KEY

2. Run with Docker Compose: Navigate to the `example` directory and run:

cd example
    # This builds the image locally based on ../Dockerfile
    # It does NOT use the public Docker Hub image
    docker-compose up --build

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.

Command-Line Options

The `openapi-mcp` command accepts the following flags:

Note: You can get this list by running the tool with the `--help` flag (e.g., `docker run --rm ckanthony/openapi-mcp:latest --help`).

Environment Variables

• `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.