README - openAPI_mcp_server by steffenhebestreit

OpenAPI MCP Server

An MCP (Model Context Protocol) server that imports OpenAPI YAML specifications and translates endpoints to MCP tool uses. This allows AI assistants to interact with REST APIs described by OpenAPI specifications.

Features

OpenAPI Import: Load OpenAPI specifications from local files or URLs
Automatic Tool Generation: Convert API endpoints to MCP tools
Request/Response Handling: Full support for HTTP methods, parameters, and request bodies
Docker Support: Easy deployment with Docker containers
Flexible Configuration: Environment variables and command-line arguments

Quick Start

Using Docker (Recommended)

Create environment configuration:

cp .env.example .env
# Edit .env with your API keys and configuration

Build and run with docker-compose: This is the easiest way to get started. It uses the settings in docker-compose.yml and .env.
```
docker-compose up --build
```
To use a different specification file, edit the volumes section in docker-compose.yml.

Or build and run manually:

# Build the Docker image using the Dockerfile in src/
docker build -t openapi-mcp-server -f src/Dockerfile .

# Run with environment file, mounting the template spec
docker run --rm -it --env-file .env -v ./template_openapi.yaml:/app/openapi.yaml openapi-mcp-server

Local Development

Install dependencies:
```
pip install -r src/requirements.txt
```

Create environment configuration:

cp .env.example .env
# Edit .env with your API keys and configuration

Run the server: The server will use the OPENAPI_SPEC_PATH or OPENAPI_SPEC_URL from your .env file.
```
python -m src.openapi_mcp_server
```

Configuration

The server can be configured using:

Environment Variables

Create a .env file in the project root (copy from .env.example):

# OpenAPI specification source (use path or URL)
OPENAPI_SPEC_PATH=./template_openapi.yaml
# OPENAPI_SPEC_URL=https://petstore.swagger.io/v2/swagger.yaml

# Dynamic server configuration (replaces placeholders in OpenAPI spec)
SERVER_URL=https://petstore.swagger.io/v2
SERVER_DESCRIPTION=Pet Store Server

# API Authentication
API_KEY=your-api-key-here
PETSTORE_AUTH=Bearer your-auth-token-here

# Server configuration
LOG_LEVEL=INFO
DEBUG=false

OpenAPI Spec Placeholders

You can use environment variable placeholders in your OpenAPI specification:

servers:
  - url: ${SERVER_URL}
    description: ${SERVER_DESCRIPTION}

These placeholders will be automatically replaced with values from your .env file when the server loads the specification.

Authentication Support

The server automatically includes authentication headers from environment variables:

API_KEY: Added as api_key header
PETSTORE_AUTH: Added as Authorization header

Define authentication in your OpenAPI spec:

components:
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: header
    petstore_auth:
      type: apiKey
      name: Authorization
      in: header

security:
  - api_key: []
  - petstore_auth: []

OpenAPI Support

The server supports OpenAPI 3.0 specifications with the following features:

Supported Operations

GET, POST, PUT, DELETE, PATCH methods
Path parameters (e.g., /pet/{petId})
Query parameters
Header parameters
Request bodies (JSON)

Tool Generation

Each API endpoint becomes an MCP tool with:

Name: Based on operationId or auto-generated from method and path
Description: From summary or description fields
Input Schema: Generated from parameters and request body schemas

Example Tool Generation

Given this OpenAPI endpoint:

/pet/{petId}:
  get:
    summary: Find pet by ID
    operationId: getPetById
    parameters:
      - name: petId
        in: path
        required: true
        schema:
          type: integer

The server generates an MCP tool:

Name: getpetbyid
Description: "Find pet by ID"
Input: {"petId": 123}

Example OpenAPI Files

The repository includes a useful example OpenAPI specification:

template_openapi.yaml: Simple pet store API for basic testing

Docker Usage

Build Options

# Build using the Dockerfile in the src directory
docker build -t openapi-mcp-server -f src/Dockerfile .

# Build with custom tag
docker build -t my-org/openapi-mcp-server:v1.0 -f src/Dockerfile .

Runtime Options

# Mount a local OpenAPI file
# The container expects the file at /app/openapi.yaml
docker run --rm -it --env-file .env -v ./template_openapi.yaml:/app/openapi.yaml openapi-mcp-server

# Use environment variables to fetch a remote spec
docker run --rm -it -e OPENAPI_SPEC_URL=https://api.example.com/openapi.yaml openapi-mcp-server

Development

Project Structure

openapi-mcp/
├── src/
│   ├── openapi_mcp_server/
│   │   ├── __init__.py
│   │   ├── __main__.py
│   │   └── server.py          # Main server implementation
│   ├── Dockerfile
│   └── requirements.txt
├── template_openapi.yaml      # Simple pet store example
├── docker-compose.yml
├── .env.example
├── LICENSE
└── README.md

Key Components

server.py: Main MCP server implementation
- OpenAPI specification loading
- Tool generation from API endpoints
- HTTP request execution
- Response formatting
__main__.py: Entry point for running as a module

Adding Features

To extend the server:

Custom Authentication: Modify _execute_api_call to add auth headers
Response Formatting: Enhance response processing in _execute_api_call
Parameter Validation: Add validation in _generate_input_schema
Error Handling: Improve error messages and recovery

Troubleshooting

Common Issues

OpenAPI File Not Found
- Ensure the file path is correct
- Check file permissions
- Verify Docker volume mounts
Network Errors
- Check internet connectivity for remote URLs
- Verify API server availability
- Check firewall settings
Invalid OpenAPI Specification
- Validate your OpenAPI file using online validators
- Ensure it follows OpenAPI 3.0 format
- Check for syntax errors in YAML
Authentication Issues
- Verify API keys are set in .env file
- Check that environment variables are loaded
- Ensure API key names match OpenAPI security schemes
- Test API endpoints manually with authentication

Logging

The server provides detailed logging. To increase verbosity, set LOG_LEVEL=DEBUG in your .env file.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0).

You are free to:

Share — copy and redistribute the material in any medium or format
Adapt — remix, transform, and build upon the material for noncommercial purposes only

Under the following terms:

Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made
NonCommercial — You may not use the material for commercial purposes

See the file for full details or visit https://creativecommons.org/licenses/by-nc/4.0/