MCP 服务器

OpenAPI MCP Server

Dynamically exposes any OpenAPI/Swagger API as tools for AI assistants, automatically generating MCP tools from OpenAPI specs with authentication support.

README

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

Clone this repository

Create a virtual environment (recommended):

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

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:

Bearer Token: Set via API_KEY environment variable
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

Spec Loading: The server loads and parses the OpenAPI specification
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
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