openapi-mcp-server

The openapi-mcp-server is a powerful bridge between OpenAPI specifications and AI assistants using the Model Context Protocol (MCP). It automatically converts any OpenAPI/Swagger API specification into MCP tools that can be used by AI assistants like Claude Desktop. This enables AI assistants to seamlessly interact with your APIs, making them capable of performing real-world actions through your services without requiring custom integrations.

Features

• 🔌 OpenAPI Integration
  • Automatically converts OpenAPI/Swagger specifications into MCP tools
• 🧩 Parameter Validation
  • Automatically validates API parameters using Zod
• 📚 Multiple OpenAPI Versions
  • Support for OpenAPI v3.0.0 and v3.1.0
• 🔐 Authentication Support:
  • HTTP authentication schemes:
    • Basic authentication
    • Bearer token authentication (JWT)
    • Other HTTP schemes as defined by RFC 7235
  • API keys:
    • Header-based API keys

Limitations

⚠️ Version Support:

• [ ] OpenAPI v2.0 (Swagger) is not currently supported

⚠️ Authentication Limitations:

• [ ] OAuth 2.0 authentication is not supported
• [ ] OpenID Connect Discovery is not supported
• [ ] Query parameter-based API keys are not supported
• [ ] Cookie-based authentication is not supported

Installation

# Clone the repository
git clone https://github.com/sotayamashita/openapi-mcp-server.git
cd openapi-mcp-server

# Install dependencies
bun install

Usage

You can run the server by providing an OpenAPI specification URL or file path:

# Using a local file
bun run src/index.ts ./path/to/openapi.yml

# Using a URL
bun run src/index.ts --api https://example.com/api-spec.json

Configuration

Environment Variables

• BASE_URL

  • Required: Yes
  • Description: API endpoint. Server Object's URL

• HEADERS

  • Required: No
  • Default: {"Content-Type": "application/json","User-Agent": "openapi-mcp-server"}
  • Description: Custom headers that will overwrite default headers

Claude Desktop Integration

To use this MCP server with Claude Desktop:

1. Open your Claude Desktop configuration file:

   # macOS/Linux
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. Add the following configuration:

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

For more detailed instructions, see the MCP quickstart guide.

Cursor Integration

To use this MCP server with Cursor as Global:

1. Open Cursor
2. Open Cursor Settings > MCP
3. Click "+ Add new global MCP Server"
4. Add the following configuration:

   {
     "mcpServer": {
       "openapi-mcp-server": {
         "command": "bun",
         "args": [
           "/path/to/openapi-mcp-server/src/index.ts",
           "/path/to/openapi-mcp-server/demo/openapi.yml"
         ],
         "env": {
           "BASE_URL": "https://api.example.com/v1/",
           "HEADERS": "{\"Authorization\": \"Bearer ****\"}"
         }
       }
     }
   }
   

For more detailed instructions, see the Cursor's Model Context Protocol.

Best Practices

OpenAPI/Swagger Specifications

Use Descriptive operationId Fields

The operationId field in your OpenAPI/Swagger specification plays a crucial role in how tools are presented to AI assistants. When converting your API to MCP tools:

• Tool Naming: The operationId is used directly as the MCP tool name
• Clarity: Descriptive operationId values make it easier for AI assistants to understand and use your API
• Consistency: Use a consistent naming pattern (e.g., getUser, createUser, updateUserPassword)

Example of a well-defined operation:

paths:
  /users/{userId}:
    get:
      operationId: getUserById
      summary: Retrieve user information
      description: Returns detailed information about a specific user

Without an operationId, the server attempts to generate a name using the HTTP method and path, but this is less descriptive and may lead to less intuitive tool names for AI assistants.

Development

Development Commands

# Run simple api server for test using simple demo/openapi.yml
bun start:server

# Run @modelcontextprotocol/inspector
bun start:inspector

# Run simple api server and @modelcontextprotocol/inspector concurrently
bun start

# Run tests
bun test

# Run tests with watch mode
bun test --watch

# Run tests with coverage
bun test --coverage

# Format code
bun run format

Codebase Structure

For details on the codebase structure and module responsibilities, see Codebase Structure.