OpenAPI MCP Server

A Model Context Protocol (MCP) server that dynamically exposes OpenAPI/Swagger APIs as tools for AI assistants.

Overview

This MCP server automatically generates tools from OpenAPI specifications, allowing AI assistants to interact with any API that has an OpenAPI/Swagger definition. Each API endpoint becomes a callable tool with proper parameter handling and authentication support.

Related MCP server: Any API MCP Server

Features

• Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI operations

• Multiple Authentication Methods: Supports Bearer tokens, custom headers, and API keys

• Flexible Spec Loading: Load OpenAPI specs from local files or URLs

• Full HTTP Method Support: GET, POST, PUT, DELETE, PATCH operations

• Parameter Handling: Supports path, query, header parameters and request bodies

• Error Handling: Comprehensive error reporting and logging

Installation

1. Clone this repository

2. Create a virtual environment (recommended):

   python -m venv myenv
   source myenv/bin/activate  # On Windows: myenv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

Why Use a Virtual Environment?

Using a virtual environment is strongly recommended because:

• Isolation: Keeps project dependencies separate from system Python packages

• Version Control: Ensures consistent package versions across different machines

• Clean Development: Prevents conflicts between different projects' dependencies

• Easy Cleanup: Simply delete the virtual environment folder to remove all packages

Virtual Environment Commands

Creating and activating:

# Create virtual environment
python -m venv myenv

# Activate on macOS/Linux
source myenv/bin/activate

# Activate on Windows
myenv\Scripts\activate

# Activate on Windows (PowerShell)
myenv\Scripts\Activate.ps1

Deactivating:

deactivate

Verifying activation:

# Check if virtual environment is active
which python  # On macOS/Linux
where python  # On Windows

# Should show path to your virtual environment's Python

Usage

Basic Usage

Run the server with a local OpenAPI spec file:

python openapi-mcp-server.py petstore.yaml

Or using environment variables:

export OPENAPI_SPEC_PATH=petstore.yaml
python openapi-mcp-server.py

Configuration

The server can be configured using environment variables:

• OPENAPI_SPEC_PATH: Path or URL to the OpenAPI specification

• OPENAPI_BASE_URL: Override the base URL from the spec (optional)

• API_KEY: Bearer token for API authentication (optional)

Authentication

The server supports multiple authentication methods:

1. Bearer Token: Set via API_KEY environment variable

2. Custom Headers: Pass auth parameters in tool calls:

   • _auth_profileId: For X-IHR-Profile-ID header

   • _auth_sessionId: For X-IHR-Session-ID header

   • _auth_token: For Authorization Bearer token

MCP Integration

To use this server with an MCP client, add it to your MCP configuration:

{
  "mcpServers": {
    "openapi": {
      "command": "python",
      "args": ["/path/to/openapi-mcp-server.py"],
      "env": {
        "OPENAPI_SPEC_PATH": "/path/to/your-api-spec.yaml",
        "OPENAPI_BASE_URL": "https://api.example.com",
        "API_KEY": "your-api-key"
      }
    }
  }
}

How It Works

1. Spec Loading: The server loads and parses the OpenAPI specification

2. Tool Generation: Each API operation becomes an MCP tool with:

   • Name from operationId

   • Description from operation description or summary

   • Input schema generated from parameters and request body

3. Tool Execution: When a tool is called:

   • Path parameters are substituted

   • Query parameters are added to the URL

   • Headers are set (including auth)

   • Request body is sent as JSON

   • Response is returned as formatted JSON

Example Tools

For a typical OpenAPI spec, the server might generate tools like:

• getPetById: Fetch a pet by ID

• addPet: Add a new pet to the store

• updatePet: Update an existing pet

• deletePet: Delete a pet

Each tool will have appropriate parameters based on the API definition.

Development

Testing

The repository includes several utility scripts:

• test-mcp-server.py: Test the MCP server functionality

• inspect-mcp-api.py: Inspect available MCP APIs

• check-mcp-install.py: Verify MCP installation

• mcp-openapi-generator-python.py: Generate Python code from OpenAPI specs

Logging

The server includes comprehensive logging. Set the log level via the standard Python logging configuration.

Requirements

• Python 3.7+

• Dependencies listed in requirements.txt:

  • mcp>=0.1.0

  • httpx>=0.25.0

  • pyyaml>=6.0

  • pydantic>=2.0.0

License

[Specify your license here]

Contributing

[Add contribution guidelines if applicable]