MCP Swagger Server
zaizaizhaoLABSCO SUMMARY
The fastest path from an existing API to an MCP tool surface.
If a service already publishes an OpenAPI 3.0 document, this is two environment variables away from being usable by an agent, with no per-endpoint code. The lever worth learning is the route map: a spec with hundreds of paths would flood the model's tool list, and a method-plus-pattern filter cuts it to the handful that matter.
What it is
A converter that reads an OpenAPI 3.0 document and exposes the API it describes as MCP tools. It runs locally over stdio, or in Docker as a streamable-HTTP server.
What you get
- Tools generated from the spec, so an internal API becomes callable without writing a server
- HTTP header pass-through, so the caller's auth header reaches the upstream service
- Route filtering with
ROUTE_MAPS— a list of HTTP methods plus a regex pattern, so only the endpoints you want become tools - Two deployment shapes from the same package:
uvx openapi2mcpserverfor local stdio, or the published Docker image for a shared streamable-HTTP endpoint - A server name you set yourself with
SERVER_NAME, which is what the client will show
Requirements
Two environment variables do the work: BASE_URL for your API host and OPEN_API_DOC_JSON_URL for the spec JSON. Set them in the client config, in a .env file at the project root, or as -e flags on the Docker run, which publishes port 9087.
Setup effort
One command — uvx openapi2mcpserver
USE CASES
01
Exposing an internal service to an agent
Point the converter at the service's spec URL and its host, and the endpoints show up as tools in your client.
02
Keeping the tool list small
Set a route map that matches only the path prefix and methods you want, instead of every operation in the spec.
03
Sharing one instance with a team
Run the Docker image with the spec and host as environment variables and let clients connect over streamable HTTP.
BEFORE YOU INSTALL
What to know first
Requires
uvx on PATH
Where it runs
All 4 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx openapi2mcpserverMCP Clients
Windsurf, Cursor, Claude Desktop
JSON
{
"mcpServers": {
"openapi2mcpserver": {
"disabled": false,
"command": "uvx",
"args": [
"openapi2mcpserver"
],
"env": {
"BASE_URL": "<YOUR_OPEN_API_DOC_JSON_URL>",
"OPEN_API_DOC_JSON_URL": "<YOUR_OPEN_API_DOC_JSON_URL> doc json url"
}
}
}
}Cline
CLINE · JSON
{
"mcpServers": {
"openapi2mcpserver": {
"command": "uvx",
"args": [
"openapi2mcpserver"
],
"env": {
"BASE_URL": "<YOUR_OPEN_API_DOC_JSON_URL>",
"OPEN_API_DOC_JSON_URL": "<YOUR_OPEN_API_DOC_JSON_URL> doc json url"
}
}
}
}
