mcp-openapi

This MCP server exposes OpenAPI-defined REST endpoints as MCP tools, enabling large language models to discover and invoke API operations through the MCP protocol. It supports two transport methods: the Stdio Transport, which is ideal for direct integration with clients like Claude Desktop via standard input/output, and the Streamable HTTP Transport, which exposes the MCP interface over HTTP for web clients and HTTP-capable tools. You can run the server with npx, and either point it at an OpenAPI spec via a URL/file or supply the spec inline or through stdin. Once running, you can list available tools derived from the OpenAPI specification and execute them by name, with results streamed back to the client. This makes REST APIs self-describing and accessible to MCP-enabled assistants and workflows.

Prerequisites:

• Node.js and npm installed on your machine
• Basic familiarity with MCP concepts and the target OpenAPI spec

Step-by-step installation:

1. Ensure Node.js and npm are installed

   • Check versions: node -v and npm -v

2. Install and run the MCP server with npx (no local install required)

# Run the OpenAPI MCP server via npx (example)
npx @ivotoby/openapi-mcp-server \
  --api-base-url https://api.example.com \
  --openapi-spec https://api.example.com/openapi.json \
  --transport http \
  --port 3000

3. Alternative: install as a local dependency (optional)

npm install --save @ivotoby/openapi-mcp-server
# Then run using npx or a script that invokes the binary/module as appropriate

4. Configuration via environment or CLI (examples)

# Environment-based configuration (example)
export API_BASE_URL=https://api.example.com
export OPENAPI_SPEC_PATH=https://api.example.com/openapi.json
export TRANSPORT_TYPE=http
export HTTP_PORT=3000

npx @ivotoby/openapi-mcp-server --api-base-url $API_BASE_URL --openapi-spec $OPENAPI_SPEC_PATH --transport http --port 3000

5. Optional: run using Docker (if you have a containerized workflow available)

• Build or pull a prebuilt image and map ports accordingly depending on your deployment setup.

Note: The exact CLI flags may vary by version. Refer to the package documentation for the latest options.

Tips and common considerations:

• OpenAPI_SPEC_PATH can be a remote URL, a local file path, or inline content via OPENAPI_SPEC_INLINE.
• If you use HTTP transport, ensure the port and host are accessible to your MCP clients.
• API_HEADERS should be a comma-separated list of header: value pairs, e.g. Authorization:Bearer token, X-API-Key: key.
• If your OpenAPI document requires external references, be mindful of how the server loads those references in your deployment environment.
• USE_PROMPTS and RESOURCES configuration (PROMPTS_PATH, PROMPTS_INLINE, RESOURCES_PATH, RESOURCES_INLINE) can customize the MCP experience with contextual prompts and resource data.
• Tools loading modes: all (default) loads all endpoint-based tools; dynamic loads only meta-tools; explicit loads only tools specified in includeTools. Adjust via TOOLS_MODE.
• If you encounter abbreviation errors, consider disabling abbreviation with DISABLE_ABBREVIATION=true, especially for long tool names.