openapi2mcp

v0.0.1-beta

Published

7 months ago

Converts OpenAPI specifications into MCP tools, enabling AI clients to interact with external APIs seamlessly.

0High
0Medium
0Low

oiloil

openapi mcp modelcontextprotocol

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):

pet_operations - Handles /pet operations:

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

pet_item_operations - Handles /pet/{petId} operations:

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

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