OpenAPI MCP Server

A Model Context Protocol (MCP) server that dynamically exposes REST APIs as MCP tools by parsing OpenAPI specifications. Works with any OpenAPI-compliant API.

Features

• Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI specs
• Two Operation Modes: Low-level (automatic) and FastMCP (predefined)
• Flexible Authentication: Support for Bearer tokens, API keys, and custom headers
• Endpoint Filtering: Whitelist/blacklist specific API endpoints
• Parameter Stripping: Remove sensitive parameters from requests
• Pre-built Presets: Includes configurations for popular APIs

Quick Start

# Install
pip install openapi-mcp-server

# Run with any OpenAPI service
openapi-mcp-server --openapi-url https://api.example.com/openapi.json --base-url https://api.example.com

# Use with Lemy (preset included)
openapi-mcp-server --preset lemy

# Test mode (verify tools without starting MCP)
openapi-mcp-server --preset lemy --test

Presets

Lemy

openapi-mcp-server --preset lemy
# or
OPENAPI_PRESET=lemy openapi-mcp-server

Custom API

openapi-mcp-server \
  --openapi-url https://your-api.com/openapi.json \
  --base-url https://your-api.com \
  --mode fastmcp \
  --auth-token your-token

Installation

From PyPI

pip install openapi-mcp-server

Or with uv:

uv add openapi-mcp-server

Local Installation (Development)

If you want to install from source for development or testing:

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

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Or with uv
uv pip install -e ".[dev]"

# Verify installation
openapi-mcp-server --help

# Run tests to ensure everything works
pytest

The editable installation (-e flag) allows you to modify the source code and see changes immediately without reinstalling.

Configuration

Environment Variables

Variable	Description	Default
OPENAPI_PRESET	Preset name (lemy, slack, etc.)	None
OPENAPI_SPEC_URL	OpenAPI specification URL	Required
API_BASE_URL	API base URL	Required
MCP_MODE	Server mode (low_level or fastmcp)	low_level
API_KEY	API authentication key	None
AUTH_HEADER	Authentication header name	Authorization
AUTH_TYPE	Authentication type	Bearer
TOOL_WHITELIST	Comma-separated endpoint patterns	None
TOOL_BLACKLIST	Comma-separated endpoint patterns	None
TOOL_NAME_PREFIX	Prefix for tool names	api_
STRIP_PARAM	Parameter to remove from requests	None
DEBUG	Enable debug logging	false

Configuration File

Create a config.json:

{
  "openapi_spec_url": "https://api.example.com/openapi.json",
  "api_base_url": "https://api.example.com",
  "mode": "fastmcp",
  "api_key": "your-token",
  "tool_whitelist": ["/users", "/posts"],
  "debug": true
}

Then run:

openapi-mcp-server --config config.json

Usage with Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "my-api": {
      "command": "openapi-mcp-server",
      "args": ["--preset", "lemy"],
      "env": {
        "API_BASE_URL": "http://localhost:11981"
      }
    }
  }
}

Or for a custom API:

{
  "mcpServers": {
    "my-api": {
      "command": "openapi-mcp-server",
      "env": {
        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
        "API_BASE_URL": "https://api.example.com",
        "API_KEY": "your-token",
        "MCP_MODE": "fastmcp"
      }
    }
  }
}

Presets

Available Presets

• lemy: Lemy AI platform
• slack: Slack API (coming soon)
• github: GitHub API (coming soon)

Creating Custom Presets

Create a preset file in presets/my-service.json:

{
  "name": "my-service",
  "openapi_spec_url": "https://api.myservice.com/openapi.json",
  "api_base_url": "https://api.myservice.com",
  "mode": "fastmcp",
  "auth_header": "X-API-Key",
  "auth_type": "Token",
  "tool_name_prefix": "myservice_",
  "fastmcp_tools": [
    {
      "name": "myservice_get_user",
      "description": "Get user information",
      "endpoint": "/users/{id}",
      "method": "GET",
      "parameters": {
        "id": {"type": "string", "required": true, "in": "path"}
      }
    }
  ]
}

Development

git clone https://github.com/yourusername/openapi-mcp-server
cd openapi-mcp-server
pip install -e ".[dev]"

# Run tests
pytest

# Test with Lemy
openapi-mcp-server --preset lemy --test

Examples

Slack API

openapi-mcp-server \
  --openapi-url https://api.slack.com/specs/openapi/v2/slack_web.json \
  --base-url https://slack.com/api \
  --auth-token xoxb-your-token \
  --tool-prefix slack_

GitHub API

openapi-mcp-server \
  --openapi-url https://api.github.com/openapi.json \
  --base-url https://api.github.com \
  --auth-token ghp_your-token \
  --auth-header Authorization \
  --auth-type "Bearer"

Custom Internal API

openapi-mcp-server \
  --openapi-url http://internal-api:8080/openapi.json \
  --base-url http://internal-api:8080 \
  --mode fastmcp \
  --whitelist "/api/v1/users,/api/v1/projects"

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for your changes
4. Ensure all tests pass
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.