openapi-to-mcp

简体中文

openapi-to-mcp is a Go implementation for converting OpenAPI specifications into MCP (Model Context Protocol) tools.

Overview

This project aims to provide a flexible framework that allows developers to automatically expose existing OpenAPI interfaces as MCP tools through simple configuration, enabling AI models to call these interfaces directly.

Features

• OpenAPI to MCP Tool Conversion: Automatically parses OpenAPI specifications and creates corresponding MCP tools based on the definitions.
• Multiple Transport Support: Supports stdio (Standard I/O), sse (Server-Sent Events), and stream (HTTP Stream) as transport protocols for MCP communication.
• State Tracking & Authentication: Supports cookie-based state tracking and JWT (JSON Web Token) handling.
• Rate Limiting: Built-in rate limiting to prevent high-frequency calls to the Large Language Model (LLM).
• Environment Variable Configuration: Flexible configuration via .env file or system environment variables.
• Stricter MCPTool Definition: Defines tools more rigorously for better usability by LLMs.

Installation

You can install openapi-to-mcp in two ways.

Option 1: Using go install (Recommended)

The easiest way to install and run the tool is using go install. After installation, the openapi-to-mcp command will be available in your shell.

go install github.com/constellation39/openapi-to-mcp@latest

Option 2: From Source

If you want to modify the code or contribute, clone the repository and build the project.

git clone https://github.com/constellation39/openapi-to-mcp cd openapi-to-mcp go build .

The executable will be ./openapi-to-mcp

Usage

Follow these steps to configure and run the tool.

Step 1: Configure Environment Variables

Create a .env file in the project's root directory or set the following environment variables in your system. You can start by copying the example file:

On Windows

copy .env.example .env

On macOS/Linux

cp .env.example .env

Then, edit the .env file with your desired configuration:

MCP transport: stdio, sse, stream (default: stdio)

MCP_TRANSPORT="stdio"

MCP BASE URL (used for sse and stream modes)

MCP_BASE_URL="http://localhost:8080"

OpenAPI specification file path (can be a local file path or a URL)

OPENAPI_SRC="./example/openapi.yaml"

Base URL for API requests

OPENAPI_BASE_URL=

Extra HTTP headers (JSON format), e.g., '{"X-API-Key": "your-api-key"}'

EXTRA_HEADERS='{"X-API-Key": "your-api-key"}'

Use cookies (true/false, default: true)

USE_COOKIE=true

Output logs to standard output (true/false, default: false)

LOG_OUTPUT=false

Rate limit: allowed requests per second (default: 1)

RATE_LIMIT_PER_SECOND=1

Authorization header, e.g., "Basic xxxx"

AUTHORIZATION_HEADERS="Basic xxxx"

Step 2: Run the Application

Execute the application from your terminal.

If you installed using go install:

openapi-to-mcp

If you built from source:

./openapi-to-mcp

For development, you can also run directly using go run:

go run main.go

Step 3: Connect with an MCP Client

Configure your MCP client to connect to openapi-to-mcp based on the MCP_TRANSPORT you've chosen.

- Stdio Mode (Default): If MCP_TRANSPORT is stdio, configure your client to execute the command directly. The env block can be used to pass or override environment variables.

{ "mcpServers": { "openapi-to-mcp": { "command": "openapi-to-mcp", "env": { "MCP_BASE_URL": "http://localhost:8080", "OPENAPI_SRC": "./example/openapi.yaml" } } } }

Note: If running from source, you might set "command" to "./openapi-to-mcp" or use go run main.go.

- SSE Mode: If MCP_TRANSPORT is sse, the server will start on the MCP_BASE_URL. Configure your client to connect to the /sse endpoint.

{ "mcpServers": { "openapi-to-mcp": { "url": "http://localhost:8080/sse" } } }

- Stream Mode: If MCP_TRANSPORT is stream, the server will start on the MCP_BASE_URL. Configure your client to connect to the /stream endpoint.

{ "mcpServers": { "openapi-to-mcp": { "url": "http://localhost:8080/stream" } } }

Please ensure http://localhost:8080 matches the MCPBASEURL in your configuration.

Project Structure

.github/
core/
  ├── openapi.go          # OpenAPI specification parsing and tool generation logic
  ├── session/            # Session management
  ├── middleware.go       # MCP middleware definitions
  └── utils.go            # Common utility functions
example/
  ├── openapi.yaml        # Example OpenAPI specification file
main.go                   # Main application entry point
README.md
README_zh.md
go.mod
go.sum

Contributing

Contributions are welcome! Feel free to submit a Pull Request or report an Issue.

License

This project is released under the MIT License.