Metadata-Version: 2.2
Name: mcp-openapi-proxy
Version: 0.1.1741388852
Summary: MCP server for exposing OpenAPI specifications as MCP tools.
Author-email: Matthew Hand <matthewhandau@gmail.com>
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.2.0
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: requests>=2.25.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: pydantic>=2.0
Requires-Dist: prance>=23.6.21.0
Requires-Dist: openapi-spec-validator>=0.7.1

# mcp-openapi-proxy

**mcp-openapi-proxy** is a Python package that implements a Model Context Protocol (MCP) server, designed to dynamically expose REST APIs—defined by OpenAPI specifications—as MCP tools. This facilitates seamless integration of OpenAPI-described APIs into MCP-based workflows.

## Overview

The package offers two operational modes:

- **Low-Level Mode (Default):** Dynamically registers tools corresponding to all API endpoints specified in an OpenAPI document (e.g., `/chat/completions` becomes `chat_completions()`).
- **FastMCP Mode (Simple Mode):** Provides a streamlined approach, exposing a predefined set of tools (e.g., `list_functions()` and `call_functions()`) based on static configurations.

## Features

- **Dynamic Tool Generation:** Automatically creates MCP tools from OpenAPI endpoint definitions.
- **Simple Mode Option:** Offers a static configuration alternative via FastMCP mode.
- **OpenAPI Specification Support:** Compatible with OpenAPI v3, with potential support for v2.
- **Flexible Filtering:** Allows endpoint filtering through whitelisting by paths or other criteria.
- **MCP Integration:** Seamlessly integrates with MCP ecosystems for invoking REST APIs as tools.

## Installation

Install the package directly from PyPI using the following command:

```bash
uvx mcp-openapi-proxy
```

### MCP Ecosystem Integration

To incorporate **mcp-openapi-proxy** into your MCP ecosystem, configure it within your `mcpServers` settings. Below is a generic example:

```json
{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_KEY": "",
                "TOOL_WHITELIST": "",
                "TOOL_NAME_PREFIX": ""
            }
        }
    }
}
```

Refer to the **Examples** section below for practical configurations tailored to specific APIs.

## Modes of Operation

### FastMCP Mode (Simple Mode)

- **Enabled by:** Setting the environment variable `OPENAPI_SIMPLE_MODE=true`.
- **Description:** Exposes a fixed set of tools derived from specific OpenAPI endpoints, as defined in the code.
- **Configuration:** Relies on environment variables to specify tool behavior.

### Low-Level Mode (Default)

- **Description:** Automatically registers all valid API endpoints from the provided OpenAPI specification as individual tools.
- **Tool Naming:** Derives tool names from normalized OpenAPI paths and methods.
- **Behavior:** Generates tool descriptions from OpenAPI operation summaries and descriptions.

## Environment Variables

- `OPENAPI_SPEC_URL`: (Required) The URL to the OpenAPI specification JSON file.
- `OPENAPI_LOGFILE_PATH`: (Optional) Specifies the log file path.
- `OPENAPI_SIMPLE_MODE`: (Optional) Set to `true` to enable FastMCP mode.
- `TOOL_WHITELIST`: (Optional) A comma-separated list of endpoint paths to expose as tools.
- `TOOL_NAME_PREFIX`: (Optional) A prefix to prepend to all tool names.

## Examples

This section will expand incrementally with new examples added periodically. Each example demonstrates how to configure **mcp-openapi-proxy** for a specific API, starting with GetZep, which leverages a free cloud API accessible with a GetZep API key.

### GetZep Example

![image](https://github.com/user-attachments/assets/6ae7f708-9494-41a1-9075-e685f2cd8873)

GetZep provides a free cloud API for memory management, making it an excellent starting point for testing. Obtain an API key from [GetZep's documentation](https://docs.getzep.com/).

#### 1. Verify the OpenAPI Specification

Retrieve the GetZep OpenAPI specification:

```bash
curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json
```

Ensure the response is a valid OpenAPI JSON document.

#### 2. Configure mcp-openapi-proxy for GetZep

Update your MCP ecosystem configuration as follows:

```json
{
    "mcpServers": {
        "getzep": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json",
                "TOOL_WHITELIST": "/sessions",
                "API_KEY": "<your_getzep_api_key>",
                "API_AUTH_TYPE": "Api-Key",
                "SERVER_URL_OVERRIDE": "https://api.getzep.com",
                "TOOL_NAME_PREFIX": "getzep"
            }
        }
    }
}
```

- **OPENAPI_SPEC_URL**: Points to the GetZep Swagger specification.
- **TOOL_WHITELIST**: Limits tools to specific endpoints (e.g., `/sessions`, `/sessions/{sessionId}/memory`).
- **API_KEY**: Your GetZep API key (replace `<your_getzep_api_key>`).
- **API_AUTH_TYPE**: Specifies `Api-Key` for GetZep’s authentication.
- **SERVER_URL_OVERRIDE**: Sets the base URL to GetZep’s API.
- **TOOL_NAME_PREFIX**: Prepends `getzep` to tool names (e.g., `getzep_sessions`).

#### 3. Resulting Tools

This configuration generates tools such as:

```json
{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"post_sessions","description":"Add Session","inputSchema":{"type":"object","properties":{},"required":[],"additionalProperties":false}},{"name":"get_sessions","description":"Get Session","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Unique identifier of the session"}},"required":["sessionId"],"additionalProperties":false}},{"name":"get_sessions-ordered","description":"Get Sessions","inputSchema":{"type":"object","properties":{"page_number":{"type":"integer","description":"Page number for pagination, starting from 1"},"page_size":{"type":"integer","description":"Number of sessions per page"},"order_by":{"type":"string","description":"Field to order results by: created_at, updated_at, user_id, session_id"},"asc":{"type":"boolean","description":"Order direction: true for ascending, false for descending"}},"required":[],"additionalProperties":false}},{"name":"get_sessions_memory","description":"Get Session Memory","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"ID of the session to retrieve memory for"},"lastn":{"type":"integer","description":"Number of most recent memory entries to retrieve"},"minRating":{"type":"number","description":"Minimum rating to filter relevant facts"}},"required":["sessionId"],"additionalProperties":false}},{"name":"post_sessions_memory","description":"Add Memory to Session","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"ID of the session to add memory to"}},"required":["sessionId"],"additionalProperties":false}},{"name":"delete_sessions_memory","description":"Delete Session","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"ID of the session to delete"}},"required":["sessionId"],"additionalProperties":false}},{"name":"get_sessions_messages","description":"Get Messages for Session","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID"},"limit":{"type":"integer","description":"Limit the number of results returned"},"cursor":{"type":"integer","description":"Cursor for pagination"}},"required":["sessionId"],"additionalProperties":false}},{"name":"post_sessions_messages_classify","description":"Classify Session","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Session ID"}},"required":["sessionId"],"additionalProperties":false}},{"name":"get_sessions_messages","description":"Get Message","inputSchema":{"type":"object","properties":{"sessionId":{"type":"string","description":"Soon to be deprecated, not needed"},"messageUUID":{"type":"string","description":"UUID of the message"}},"required":["sessionId","messageUUID"],"additionalProperties":false}}]}}
```

#### 4. Testing

Run the server with `uvx` to verify:

```bash
OPENAPI_SPEC_URL="https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json" API_KEY="<your_getzep_api_key>" uvx mcp-openapi-proxy
```

Additional examples (e.g., OpenWebUI, Fly.io) will be added incrementally to this section over time.

## Troubleshooting

- **Missing OPENAPI_SPEC_URL:** Ensure the environment variable is set to a valid OpenAPI JSON URL.
- **Invalid Specification:** Confirm the OpenAPI document adheres to the standard.
- **Tool Filtering Issues:** Verify `TOOL_WHITELIST` correctly specifies desired endpoints.
- **Logging:** Check logs at `OPENAPI_LOGFILE_PATH` (if set) for diagnostic details.
- **Installation Verification:** Test the server directly:

```bash
uvx mcp-openapi-proxy
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
