lotusbaba/openapi-mcp-server

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.

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]