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

Variable	Description	Example
API_BASE_URL	Base URL of the API	https://api.example.com

Optional

Variable	Description	Default
API_OPENAPI_PATH	Path to OpenAPI spec	/openapi.yaml
API_AUTH_TYPE	Authentication type: none, apiKey, bearer	none
API_KEY	API key (when API_AUTH_TYPE=apiKey)	-
API_KEY_HEADER	Header name for API key	X-API-Key
API_BEARER_TOKEN	Bearer token (when API_AUTH_TYPE=bearer)	-
API_TIMEOUT_MS	Request timeout in milliseconds	30000
API_CACHE_TTL_MS	OpenAPI spec cache TTL	3600000 (1 hour)

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