OpenAPI to MCP Generator

This project provides a powerful tool for automatically converting OpenAPI/Swagger specifications into Model Context Protocol (MCP) servers, allowing LLMs to interact with any REST API through standardized tools.

Components

SwaggerToMcpGenerator.java

A comprehensive utility that converts any OpenAPI/Swagger specification into a fully functional MCP server:

• Parses OpenAPI specification files
• Converts API endpoints to MCP tools
• Handles path parameters, query parameters, and request bodies
• Supports multiple HTTP methods (GET, POST, PUT, DELETE, PATCH)
• Provides authentication support (API keys, Bearer tokens, Basic auth)
• Formats JSON responses for readability
• Generates robust error handling
• Includes parameter documentation with valid values and defaults

Generating an MCP Server from OpenAPI

To generate an MCP server from any OpenAPI specification:

jbang SwaggerToMcpGenerator.java path/to/swagger.json GeneratedMcpServer [options]

Parameters:

• path/to/swagger.json: Path to the OpenAPI/Swagger specification file
• GeneratedMcpServer: Name of the output Java file (without .java extension)

Options:

• --server-index <index>: Index of the server to use from the OpenAPI specification (0-based)
• --server-url <url>: URL of the server to use (overrides server-index)

This will create a new file GeneratedMcpServer.java that implements an MCP server with tools for each API endpoint defined in the swagger file. The generator will emit a warning if multiple servers are defined in the OpenAPI specification and none is explicitly selected.

Running the Generated MCP Server

To run the generated MCP server:

jbang GeneratedMcpServer.java

Server Selection

The generated MCP server includes constants for all servers defined in the OpenAPI specification, allowing you to choose which server to use at runtime. By default, the first server in the list is used, but you can select a specific server using environment variables:

# Select server by index (0-based)
export SERVER_INDEX=1

# Or select server by URL
export SERVER_URL="https://api-example.com/v2"

jbang GeneratedMcpServer.java

Authentication

The generated MCP server supports multiple authentication methods through environment variables:

• API Key: Set API_KEY and API_KEY_HEADER environment variables
• Bearer Token: Set BEARER_TOKEN environment variable
• Basic Auth: Set API_USERNAME and API_PASSWORD environment variables

Example:

export API_KEY="your-api-key"
export API_KEY_HEADER="X-API-Key"
jbang GeneratedMcpServer.java

Examples

Open-Meteo Weather API

The project includes an example OpenAPI specification for the Open-Meteo Weather API in the examples/open-meteo directory.

Generating the Open-Meteo MCP Server

cd examples/open-meteo
jbang ../../SwaggerToMcpGenerator.java open-meteo-openapi.yml OpenMeteoMcpServer

This will generate OpenMeteoMcpServer.java with MCP tools for accessing weather forecast data.

Running the Open-Meteo MCP Server

cd examples/open-meteo
jbang OpenMeteoMcpServer.java

Using the Open-Meteo MCP Server

The generated MCP server provides tools for accessing weather forecasts. When using the server, pay attention to the parameter descriptions which include valid values and defaults. For example:

• For the wind_speed_unit parameter, use ms (not "m/s") for meters per second
• Valid values for wind_speed_unit are: kmh (default), ms, mph, and kn
• For temperature units, use celsius (default) or fahrenheit

Example query for weather in Sevilla, Spain:

latitude: 37.3891
longitude: -5.9845
current_weather: true
wind_speed_unit: ms

Generating the Clever Cloud MCP Server

cd examples/clever-cloud
jbang ../../SwaggerToMcpGenerator.java clever-cloud-openapi.yml CleverCloudMcpServer --server-index 1

Note that we're using --server-index 1 (the second server in the list) which is the API Bridge URL required for token authentication. This will generate CleverCloudMcpServer.java with MCP tools for managing Clever Cloud resources.

Alternatively, you can specify the server URL directly:

cd examples/clever-cloud
jbang ../../SwaggerToMcpGenerator.java clever-cloud-openapi.yml CleverCloudMcpServer --server-url https://api-bridge.clever-cloud.com/v2

Running the Clever Cloud MCP Server

cd examples/clever-cloud
# Set your Clever Cloud API token
export BEARER_TOKEN=your_api_token
jbang CleverCloudMcpServer.java

Generating a Clever Cloud API Token

To generate an API token for Clever Cloud, you'll need to use the Clever Tools CLI:

# Install Clever Tools (if not already installed)
npm install -g clever-tools

# Login to Clever Cloud
clever login

# Enable the tokens feature
clever features enable tokens

# Create a token (with optional expiration)
clever tokens create "MCP Server Token"
clever tokens create "Temporary Token" --expiration 24h

You can also list and revoke tokens:

# List existing tokens
clever tokens -F json

# Revoke a token
clever tokens revoke api_tokens_xxx

Using the Clever Cloud MCP Server

The generated MCP server provides tools for interacting with the Clever Cloud API. Available tools include:

• get_self: Get current user information
• get_summary: Get user summary
• get_organisations__organisationId__applications: List applications for an organization
• get_organisations__organisationId__applications__applicationId_: Get application details

Example query to list applications for an organization:

organisationId: your_organization_id

How It Works

MCP Protocol

The Model Context Protocol (MCP) is a standardized way for tools and LLMs to communicate, allowing:

1. Tools to expose their functionality to any MCP-compatible LLM
2. LLMs to discover and use tools without being tied to specific implementations
3. A consistent interface for tool specifications and invocations

OpenAPI to MCP Conversion

The generator works by:

1. Parsing the OpenAPI specification using Swagger Parser
2. Converting each API endpoint to an @Tool annotated method
3. Mapping parameters:
   • Path parameters are incorporated into the URL
   • Query parameters are added to the URL builder
   • Request bodies are properly formatted and attached to the request
4. Generating HTTP client code with proper error handling
5. Formatting responses based on content type (pretty-printing JSON)
6. Adding authentication based on environment variables

Advanced Features

• Multiple HTTP Methods: Support for GET, POST, PUT, DELETE, and PATCH
• Content Type Handling: Proper handling of different content types
• Error Handling: Detailed error reporting with status codes and response bodies
• Authentication: Support for API keys, Bearer tokens, and Basic authentication
• Timeouts: Configurable connection, read, and write timeouts
• Multiple Servers: Support for selecting from multiple server URLs defined in the OpenAPI specification

Environment Notes

The jbang-wrapper.sh script addresses environment issues when running from AI assistants like Claude Desktop on Mac, ensuring the correct PATH and environment variables are available.

Next Steps

• Add support for form data and multipart requests
• Implement OAuth 2.0 authentication flow
• Add support for custom response transformations
• Create a web UI for uploading OpenAPI specs and generating servers
• Add support for WebSocket endpoints