mcp-from-openapi 0.1.0

Convert OpenAPI 3.x specs into live, working MCP servers

openapi-to-mcp

Convert any OpenAPI 3.x spec file into a live, working MCP (Model Context Protocol) server that AI agents can connect to and use as tools.

What it does

This CLI tool parses an OpenAPI 3.x specification and generates a standalone Python script acting as an MCP server. This allows AI assistants (like Claude, Cursor, or Copilot) to understand and interact with your existing REST APIs by converting your OpenAPI endpoints into MCP tools.

How it works

1. Parse: Reads your OpenAPI specification (YAML or JSON).
2. Generate: Uses Jinja2 templates to construct a complete, standalone Python file containing the MCP server logic.
3. Run: Provides an option to immediately start the generated MCP server using the stdio or sse transport.

Installation

pip install mcp-from-openapi

For development:

git clone https://github.com/vinayakrastogi/openAPI-to-MCP-converter.git
cd openAPI-to-MCP-converter
pip install -e .

Commands

1. Inspect endpoints in a spec (dry-run)

Prints a table of all discovered endpoints, their tool names, and parameters without generating any files.

openapi-to-mcp inspect --spec examples/math_api.yaml

2. Generate a standalone MCP server

Outputs a ready-to-run Python file (e.g., output/math_api_mcp_server.py).

openapi-to-mcp generate \
  --spec examples/math_api.yaml \
  --base-url http://127.0.0.1:8000

3. Generate and immediately run

Creates the MCP server file and starts it immediately.

openapi-to-mcp run \
  --spec examples/math_api.yaml \
  --base-url http://127.0.0.1:8000

4. Run with Authentication

Injects authentication headers into every request made by the MCP server.

# Bearer token style:
openapi-to-mcp run \
  --spec examples/pet_api.yaml \
  --base-url https://api.example.com \
  --auth-header "Authorization: Bearer mytoken"

# API key style:
openapi-to-mcp run \
  --spec examples/pet_api.yaml \
  --base-url https://api.example.com \
  --auth-header "X-Api-Key: abc123"

CLI Reference

openapi-to-mcp <command> [options]

Commands:
  inspect   Parse a spec and display endpoints (dry-run, no files written)
  generate  Parse a spec and write a standalone MCP server file
  run       Generate AND immediately start the MCP server

Common Options:
  --spec,       -s  FILE    Path to the OpenAPI YAML or JSON spec file [required]
  --base-url,   -u  URL     Base URL of the live API (overrides servers[0].url)
  --auth-header,-a  HEADER  Auth header injected into every request
  --transport,  -t          MCP transport: stdio (default) or sse
  --name,       -n  NAME    Server name (defaults to spec info.title)
  --output,     -o  FILE    Output path for the generated server file

Connecting to AI Agents

Claude Desktop

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-api": {
      "command": "python",
      "args": ["/absolute/path/to/output/math_api_mcp_server.py"]
    }
  }
}

Cursor / VS Code (Copilot MCP)

Add the following to .cursor/mcp.json or your workspace MCP config:

{
  "servers": {
    "my-api": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/output/math_api_mcp_server.py"]
    }
  }
}

Supported OpenAPI Features

Feature	Status
OpenAPI 3.x (YAML & JSON)	Supported
Path parameters (in: path)	Supported
Query parameters (in: query)	Supported
Request bodies (application/json)	Supported
$ref schema resolution	Supported
operationId as tool name	Supported
Fallback tool name from method + path	Supported
Auth header injection	Supported
servers[0].url as base URL	Supported
stdio transport	Supported
SSE transport	Supported
Header parameters	Parsed, not injected (use --auth-header)
OAuth flows	Not Supported (v2 roadmap)
multipart/form-data bodies	Not Supported (v2 roadmap)