OpenAPI to MCP

Standalone proxy that turns any OpenAPI/Swagger-described HTTP API into an MCP (Model Context Protocol) server. It loads the spec at startup, filters operations by include/exclude, and registers one MCP tool per API operation. Tool calls are executed as HTTP requests to the backend API.

Useful when you already have (or want) a REST API with an OpenAPI/Swagger spec: the same spec drives both human-readable API docs and MCP tools for AI clients.

How it works

flowchart LR
  subgraph startup["Startup"]
    A[OpenAPI spec<br/>URL or file] --> B[Load and filter<br/>include or exclude]
    B --> C[N MCP tools<br/>one per operation]
  end

  subgraph runtime["Runtime"]
    D[MCP client] <-->|Streamable HTTP<br/>POST/GET /mcp| E[openapi-to-mcp]
    E <-->|HTTP| F[Backend API]
  end

  C -.->|registered in| E

1. Load OpenAPI spec from MCP_OPENAPI_SPEC_URL (preferred) or MCP_OPENAPI_SPEC_FILE.
2. Collect operations (method + path). Filter: if MCP_INCLUDE_ENDPOINTS is set, keep only those; otherwise drop any in MCP_EXCLUDE_ENDPOINTS. Include has priority over exclude.
3. For each operation create an MCP tool: name = MCP_TOOL_PREFIX + path segment (e.g. api_ + messages = api_messages). If the same path segment is used by more than one method (e.g. GET and PUT on /pet/{id}), the tool name is made unique by appending the method (e.g. pet_get, pet_put). Input schema from parameters and requestBody (Zod), handler = HTTP call to MCP_API_BASE_URL.

Transport: Streamable HTTP. Endpoint: POST /mcp and GET /mcp.

Environment variables (MCP_ prefix)

Variable	Description	Default
MCP_API_BASE_URL	Base URL for API requests	http://127.0.0.1:3000
MCP_OPENAPI_SPEC_URL	URL of OpenAPI spec (e.g. http://api:3000/openapi.json). Takes precedence over file.	-
MCP_OPENAPI_SPEC_FILE	Path to OpenAPI JSON file (used if URL not set)	-
MCP_INCLUDE_ENDPOINTS	Comma-separated method:path (e.g. get:/messages,get:/channels). If set, only these become tools.	-
MCP_EXCLUDE_ENDPOINTS	Comma-separated method:path to exclude. Ignored for endpoints in include.	-
MCP_TOOL_PREFIX	Prefix for tool names (e.g. api_ -> api_messages, api_channels)	(empty)
MCP_SERVER_NAME	Server name reported to MCP clients	openapi-to-mcp
MCP_PORT	Port for Streamable HTTP server	3100
MCP_HOST	Bind host	0.0.0.0

At least one of MCP_OPENAPI_SPEC_URL or MCP_OPENAPI_SPEC_FILE must be set.

Run with npm (local)

1. Copy .env.example to .env and set at least the OpenAPI spec source and API base URL:

   cp .env.example .env
   # Edit .env: MCP_OPENAPI_SPEC_URL or MCP_OPENAPI_SPEC_FILE, MCP_API_BASE_URL
   

2. Install, build, and start:

   npm ci
   npm run build
   npm run start
   

3. The server listens on http://<MCP_HOST>:<MCP_PORT> (default http://0.0.0.0:3100). Connect MCP clients to POST/GET http://localhost:3100/mcp (Streamable HTTP).

Ensure the backend API is reachable at MCP_API_BASE_URL and that the OpenAPI spec URL (or file) returns a valid OpenAPI 3.x JSON.

Run with Docker

Image on Docker Hub: evilfreelancer/openapi-to-mcp. Use tag latest or a version tag (e.g. v1.0.0).

1. Pull and run with env vars (example: spec from URL, API at host):

   docker run --rm -p 3100:3100 \
     -e MCP_OPENAPI_SPEC_URL=http://host.docker.internal:3000/openapi.json \
     -e MCP_API_BASE_URL=http://host.docker.internal:3000 \
     evilfreelancer/openapi-to-mcp:latest
   

   On Linux you may need --add-host=host.docker.internal:host-gateway or use the host network. Alternatively pass a file path and mount the spec:

   docker run --rm -p 3100:3100 \
     -v $(pwd)/openapi.json:/app/openapi.json:ro \
     -e MCP_OPENAPI_SPEC_FILE=/app/openapi.json \
     -e MCP_API_BASE_URL=http://host.docker.internal:3000 \
     evilfreelancer/openapi-to-mcp:latest
   

   To build the image locally instead: docker build -t openapi-to-mcp . and use openapi-to-mcp as the image name in the commands above.

Run with Docker Compose

A minimal docker-compose.yaml is included so you can run the MCP server and optionally point it at an existing API. It uses the image from Docker Hub (evilfreelancer/openapi-to-mcp).

1. Copy .env.example to .env and set:

   • MCP_OPENAPI_SPEC_URL (e.g. your API’s /openapi.json URL)
   • MCP_API_BASE_URL (e.g. http://api:3000 if the API runs in another container)

2. From the project root:

   docker compose up -d
   

3. The MCP server will be available at http://localhost:3100/mcp (Streamable HTTP).

To use a local OpenAPI file instead of a URL, set MCP_OPENAPI_SPEC_FILE and mount the file into the container (see docker-compose.yaml comments if present).

Tests

npm test

Tests cover: config (env vars, include/exclude, defaults), OpenAPI loader (URL and file, URL over file, error when both unset), and openapi-to-tools (filtering, prefix, handler calling API with success and error). HTTP is mocked (axios-mock-adapter).

Dockerfile

The project includes a Dockerfile (Node 20 Alpine): install deps, build TypeScript, production prune, run node dist/index.js. No dev dependencies or tests in the image. Pre-built images are published to Docker Hub. To build locally:

docker build -t openapi-to-mcp .

CI - Docker image on Docker Hub

A GitHub Actions workflow (.github/workflows/docker-publish.yml) runs tests, then builds the image and pushes it to Docker Hub.

• Triggers: manually (Actions → "Docker build and push" → Run workflow) or on push of any git tag.
• Version: on tag push the image tag equals the git tag (e.g. v1.0.0); on manual run you can set a version (default latest).
• Main only: when triggered by a tag, the workflow checks that the tag points to a commit on main; otherwise the run fails.

Required repository secrets (Settings → Secrets and variables → Actions):

Secret	Description
DOCKERHUB_USERNAME	Docker Hub username (image will be DOCKERHUB_USERNAME/openapi-to-mcp)
DOCKERHUB_TOKEN	Docker Hub access token (recommended) or password

Similar projects

• mcp-openapi-proxy (Python) – MCP server that exposes REST APIs from OpenAPI specs as MCP tools. Low-level mode (one tool per endpoint) or FastMCP mode. Auth and endpoint filtering. Install: uvx mcp-openapi-proxy.
• openapi-mcp-proxy (TypeScript) – CLI that turns an OpenAPI service into an MCP server; middleware between OpenAPI and MCP clients.
• openapi-mcp-generator (TypeScript) – Generates a full MCP server project from OpenAPI 3.0+ (stdio, SSE, Streamable HTTP), with Zod validation and auth. Install: npm install -g openapi-mcp-generator.
• FastMCP + OpenAPI (Python) – OpenAPI integration for FastMCP: auth, route mapping, parameter handling.
• openapi-mcp-codegen – Code generator from OpenAPI to MCP server (Apache 2.0).
• Swagger MCP (Vizioz) – AI-driven MCP server generation from Swagger/OpenAPI; stores specs locally.
• liblab – Cloud service: generate and deploy MCP server from OpenAPI or Postman collection.