evilfreelancer/openapi-to-mcp repository overview

⁠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

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), 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)

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
   

   Copy

2. Install, build, and start:

   npm ci
   npm run build
   npm run start
   

   Copy

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
   

   Copy

   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
   

   Copy

   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
   

   Copy

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

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