openapi_mcp_server

OpenAPI MCP Server acts as a Model Context Protocol (MCP) server that exposes REST API endpoints defined by an OpenAPI specification. It enables large language models (LLMs) to interact with the specified HTTP APIs by performing GET, PUT, POST, and PATCH requests through the MCP context. You configure the server with the location of the OpenAPI document and the base URL of the target API, and you can optionally restrict which operations the MCP can call via white/black lists and add custom headers. The server runs under uv (Uvicorn-style runner) and can be managed with standard environment variables to tailor the requests (e.g., API_BASE_URL, OPENAPI_SPEC_PATH, and API_HEADERS). When integrated with tools like Claud Desktop, you can point a client to the MCP server and it will translate LLM prompts into concrete REST API calls described by the OpenAPI spec.

Prerequisites:

• Python installed (3.8+ recommended)
• pip available in PATH
• uv (the OpenAPI MCP runner) and the package can be installed via pip

Step-by-step installation:

# 1) Install the OpenAPI MCP Server package
pip install openapi_mcp_server

# 2) Prepare a folder for configuration and a minimal .env with required values
# Create a file named .env in the working folder with at least:
# OPENAPI_SPEC_PATH=http://petstore.swagger.io/v2/swagger.json
# API_BASE_URL=https://petstore.swagger.io/v2

# 3) Run the server using uv as described by the README
uv run openapi_mcp_server

Optional setup:

• Create and edit the .env file to include:
  • DEBUG (optional)
  • OPENAPI_SPEC_PATH
  • API_BASE_URL
  • API_HEADERS
  • API_WHITE_LIST
  • API_BLACK_LIST
  • HTTP_PROXY / HTTPS_PROXY / NO_PROXY as needed

Test run example (from the project folder):

uv run openapi_mcp_server

Tips and notes:

• Ensure OPENAPI_SPEC_PATH points to a valid OpenAPI document and API_BASE_URL matches the target API's base URL.
• Use API_HEADERS to pass required authentication or content negotiation headers.
• If you plan to restrict operations for safety or cost, fill API_WHITE_LIST with the allowed operationIds.
• When using Claud Desktop or similar tooling, the mcp_config can be integrated directly to drive prompts that translate to REST calls.
• Debug mode (DEBUG=1) can help diagnose request construction or OpenAPI parsing issues.
• If you encounter proxy-related failures, configure HTTP_PROXY/HTTPS_PROXY and NO_PROXY appropriately for your environment.