OpenAPI2MCP

OpenAPI2MCP that allows AI clients to call any OpenAPI-compatible REST API through the MCP interface. This tool converts OpenAPI specifications into MCP tools, enabling AI clients to interact with external APIs seamlessly.

Features

• ✨ Universal API Support: Works with any OpenAPI 2.0/3.0 compatible API
• 🔄 Multiple Transport Modes: STDIO, HTTP, and SSE (Server-Sent Events)
• 🔐 Flexible Authentication: Support for API keys, Bearer tokens, and custom headers
• 🔧 Easy Configuration: Support for environment variables and URL parameter configuration
• 🎯 Smart API Merging: Intelligently merge related API endpoints into unified tools to reduce tool count for AI clients with limitations (e.g., Cursor)
• 💾 Efficient Caching: Support for OpenAPI specification caching to improve performance

Quick Start

Prerequisites

• Node.js 18+ and pnpm
• An OpenAPI specification (JSON or YAML)
• API credentials (if required)
• An MCP-compatible client (Claude Desktop, Cursor, Cline, etc.)

Installation and Build

git clone https://github.com/oil-oil/openapi2mcp.git
cd openapi2mcp
pnpm install
pnpm run build

MCP Client Configuration

STDIO Mode

Configure your MCP client by adding the following to your configuration file:

{
  "mcpServers": {
    "openapi2mcp": {
      "command": "npx",
      "args": ["-y", "openapi2mcp"],
      "env": {
        "TRANSPORT_TYPE": "stdio",
        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
        "OPENAPI_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
        "HEADER.Authorization": "Bearer your-token-here",
        "HEADER.Content-Type": "application/json"
      }
    }
  }
}

SSE Mode

First, start the SSE server:

pnpm start:sse

Then configure your MCP client:

{
  "mcpServers": {
    "openapi2mcp": {
      "url": "http://localhost:3000/sse?base_url=https://petstore3.swagger.io/api/v3&openapi_spec=https://petstore3.swagger.io/api/v3/openapi.json&headers.Content-Type=application%2Fjson&message_path=/custom/message"
    }
  }
}

Available SSE Parameters:

• base_url - API base URL (required)
• openapi_spec - OpenAPI specification URL (required)
• message_path - Custom message endpoint path (optional, default: /message)
• headers.* - Custom headers (optional)
• merge_api - Enable API merging (optional, default: false)
• Cache parameters: cache_enabled, cache_ttl, etc.

Testing Your Setup

Once configured, you can test your setup by asking your AI client:

• "Find pets by status in the pet store"
• "Get pet by id xxxx"
• "Add a new pet to the store, name: doggie, photoUrls: [url1]"

Core Features

API Merging Feature

Some AI clients (like Cursor) have limitations on the number of MCP tools they can handle effectively. The API merging feature intelligently combines related API endpoints into unified tools, significantly reducing the total number of tools while maintaining full functionality.

How It Works

When enabled, the OpenAPI2MCP groups API endpoints by resource path and merges them into comprehensive tools. For example, instead of having separate tools for each HTTP method, you get a single tool that handles multiple operations through an object-based parameter structure.

Petstore API Example

Without Merging (8 individual tools):

• get_pet_petId - GET /pet/{petId}
• post_pet_petId - POST /pet/{petId}
• delete_pet_petId - DELETE /pet/{petId}
• get_pet_findByStatus - GET /pet/findByStatus
• get_pet_findByTags - GET /pet/findByTags
• post_pet - POST /pet
• put_pet - PUT /pet
• post_pet_petId_uploadImage - POST /pet/{petId}/uploadImage

With Merging Enabled (3 unified tools):

1. pet_operations - Handles /pet operations:

   {
     "operation": {
       "get": { "status": "available" },
       "post": { "body": { "name": "doggie", "photoUrls": ["url1"] } },
       "put": { "body": { "id": 1, "name": "doggie" } }
     }
   }
   

2. pet_item_operations - Handles /pet/{petId} operations:

   {
     "operation": {
       "get": { "petId": "1" },
       "post": { "petId": "1", "name": "doggie" },
       "delete": { "petId": "1" }
     }
   }
   

3. pet_item_uploadImage_operations - Handles /pet/{petId}/uploadImage:

   {
     "operation": {
       "post": { "petId": "1", "body": { "additionalMetadata": "test" } }
     }
   }
   

Caching Feature

The OpenAPI caching feature provides efficient caching for parsed OpenAPI specifications and generated tools in SSE mode, significantly improving performance by avoiding repeated parsing and tool generation when connecting to the same API.

Usage Example

First connection (cache miss):

[Fresh] Loaded OpenAPI 3.0: Swagger Petstore v1.0.17
[Fresh] Found 19 API endpoints
[Cache] Cached OpenAPI spec: https://petstore3.swagger.io/api/v3/openapi.json (expires in 3600s)

Subsequent connections (cache hit):

[Cache] Cache hit for OpenAPI spec: https://petstore3.swagger.io/api/v3/openapi.json
[Cache] Using cached OpenAPI 3.0: Swagger Petstore v1.0.17
[Cache] Found 19 API endpoints, 19 tools

Monitoring

You can monitor cache performance through the health endpoint:

curl http://localhost:3000/health

Configuration

Environment Variables

Basic Configuration

Variable	Description	Default	Required
TRANSPORT_TYPE	Transport mode: stdio, http, sse	stdio	No
SSE_PORT	Port for HTTP/SSE server	3000	No
API_BASE_URL	Base URL for API requests	-	No**
OPENAPI_SPEC_URL	URL to fetch OpenAPI spec	-	Yes*
OPENAPI_SPEC_PATH	Local path to OpenAPI spec file	-	Yes*

*Either OPENAPI_SPEC_URL or OPENAPI_SPEC_PATH is required. **API_BASE_URL is optional when OpenAPI specification contains servers field. The first server URL will be used automatically.

Request Configuration

Variable	Description	Default	Required
VERIFY_SSL	Enable SSL certificate verification	true	No
TIMEOUT	Request timeout in milliseconds	30000	No
HEADER.*	Custom headers	-	No
HEADERS	JSON string of headers (legacy)	-	No

Feature Configuration

Variable	Description	Default	Required
MERGE_API	Enable API merging to reduce tool count	false	No

Cache Configuration

Variable	Description	Default	Required
CACHE_ENABLED	Enable OpenAPI specification caching	true	No
CACHE_TTL	Cache time-to-live in seconds	3600	No
CACHE_MAX_SIZE	Maximum number of cached entries	200	No
CACHE_CHECK_INTERVAL	Cache cleanup interval in seconds	300	No

Header Configuration

Recommended Format (HEADER.xxx)

{
  "mcpServers": {
    "openapi2mcp": {
      "command": "npx",
      "args": ["-y", "openapi2mcp"],
      "env": {
        "TRANSPORT_TYPE": "stdio",
        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
        "OPENAPI_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
        "HEADER.Authorization": "Bearer your-token-here",
        "HEADER.Content-Type": "application/json",
        "HEADER.X-API-Key": "your-api-key"
      }
    }
  }
}

URL Parameter Format (SSE Mode)

http://localhost:3000/sse?base_url=https://petstore3.swagger.io/api/v3&openapi_spec=https://petstore3.swagger.io/api/v3/openapi.json&headers.Authorization=Bearer%20your-token&headers.Content-Type=application%2Fjson

Note: Headers in URL parameters must be URL encoded (spaces: %20, slashes: %2F)

Legacy JSON Format

{
  "mcpServers": {
    "openapi2mcp": {
      "command": "npx",
      "args": ["-y", "openapi2mcp"],
      "env": {
        "TRANSPORT_TYPE": "stdio",
        "API_BASE_URL": "https://petstore3.swagger.io/api/v3",
        "OPENAPI_SPEC_URL": "https://petstore3.swagger.io/api/v3/openapi.json",
        "HEADERS": "{\"Authorization\":\"Bearer your-token\",\"Content-Type\":\"application/json\"}"
      }
    }
  }
}

Development

Running Tests

pnpm run dev

# Run tests
pnpm test

# Build project
pnpm run build

Docker Deployment

Build and Run

# Build image
docker build -t openapi2mcp .

# Run with environment variables
docker run -e TRANSPORT_TYPE=http \
           -e API_BASE_URL=https://petstore3.swagger.io/api/v3 \
           -e OPENAPI_SPEC_URL=https://petstore3.swagger.io/api/v3/openapi.json \
           -e HEADER.Authorization="Bearer token" \
           -p 3000:3000 \
           openapi2mcp