OpenAPI MCP Server

A generic Model Context Protocol (MCP) server that exposes any OpenAPI-documented REST API to LLMs like Claude.

Features

• Auto-discovers endpoints from any OpenAPI 3.x specification (YAML or JSON)

• Two simple tools: api_discover and api_request

• Flexible authentication: None, API Key, or Bearer token

• Caching: Caches OpenAPI spec locally with configurable TTL

• Retry logic: Automatic retry on rate limits (429) with exponential backoff

Installation

npm install @cloudwarriors/openapi-mcp

Or run directly with npx:

npx @cloudwarriors/openapi-mcp

Configuration

The server is configured via environment variables:

Required

Optional

Usage with Claude Code

Add to your .mcp.json or Claude Code settings:

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@cloudwarriors/openapi-mcp"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "API_OPENAPI_PATH": "/docs/openapi.yaml"
      }
    }
  }
}

Example: Connecting to Hermes

{
  "mcpServers": {
    "hermes": {
      "command": "npx",
      "args": ["@cloudwarriors/openapi-mcp"],
      "env": {
        "API_BASE_URL": "http://localhost:3345",
        "API_OPENAPI_PATH": "/api/docs/openapi.yaml"
      }
    }
  }
}

Example: Connecting to a Protected API

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@cloudwarriors/openapi-mcp"],
      "env": {
        "API_BASE_URL": "https://api.mycompany.com",
        "API_OPENAPI_PATH": "/openapi.json",
        "API_AUTH_TYPE": "bearer",
        "API_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}

Tools

api_discover

Lists all available API endpoints grouped by domain/tag.

Parameters:

• domain (optional): Filter endpoints by domain/tag

• includeParameters (optional): Include parameter details (default: false)

Example:

{ "domain": "users", "includeParameters": true }

api_request

Makes an HTTP request to any API endpoint.

Parameters:

• method (required): HTTP method (GET, POST, PUT, DELETE, PATCH)

• path (required): API path (e.g., /api/users/{id})

• body (optional): Request body for POST/PUT/PATCH

• query (optional): Query parameters as key-value pairs

• pathParams (optional): Path parameter substitutions

Example:

{
  "method": "GET",
  "path": "/api/users/{id}",
  "pathParams": { "id": "123" }
}

Finding Your API's OpenAPI Spec

Common locations for OpenAPI specifications:

• /openapi.yaml or /openapi.json

• /api/docs/openapi.yaml

• /swagger.json

• /v1/openapi.json

• /api-docs

Check your API's documentation or try accessing these paths directly.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode (watch)
npm run dev

License

MIT

Author

CloudWarriors