# mcpo

> MCP Server

**Concise Description:**

MCP-to-OpenAPI proxy. Securely exposes Model Context Protocol data via OpenAPI.

## Overview

- **Category:** Communication
- **Language:** Python
- **Stars:** 4342
- **Forks:** 295
- **Owner:** open-webui
- **GitHub:** https://github.com/open-webui/mcpo
- **Homepage:** https://docs.openwebui.com/openapi-servers/mcp
- **Created:** 2025-03-30T10:03:03+00:00
- **Updated:** 2025-07-07T15:56:47+00:00
- **Source:** https://model-context-protocol.com/servers/mcpo

## Setup

## Setup

### Prerequisites

*   Python 3.8+
*   uv (optional, but highly recommended for performance and packaging)

### Installation

There are several ways to install and run `mcpo`:

**1. Using uv (Recommended):**

uv provides lightning-fast startup and zero configuration.

```bash
uv pip install mcpo
```

**2. Using pip:**

If you prefer using `pip`:

```bash
pip install mcpo
```

**3. Running via Docker (No Installation Required):**

This method avoids the need for local installations.

```bash
docker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --api-key "top-secret" -- your_mcp_server_command
```

### Configuration and Usage

After installation, you can run `mcpo` with the following options:

**Basic Usage:**

```bash
mcpo --port 8000 --api-key "your-secret-api-key" -- your_mcp_server_command
```

*   `--port`:  The port on which `mcpo` will listen for incoming HTTP requests (default: 8000).
*   `--api-key`:  An API key for securing access to the `mcpo` server.  **Important:** Replace `"your-secret-api-key"` with a strong, unique key.
*   `your_mcp_server_command`: The command to execute your MCP server.  This is the core functionality that `mcpo` exposes via HTTP.

**Example with `mcp-server-time`:**

```bash
uvx mcpo --port 8000 --api-key "top-secret" -- uvx mcp-server-time --local-timezone=America/New_York
```

**SSE-Compatible MCP Server:**

If your MCP server uses Server-Sent Events (SSE):

```bash
mcpo --port 8000 --api-key "top-secret" --server-type "sse" -- http://127.0.0.1:8001/sse
```

*   `--server-type "sse"`: Specifies that the MCP server uses SSE.
*   `http://127.0.0.1:8001/sse`: The URL of your SSE server.

**SSE Headers:**

To include custom headers with the SSE connection:

```bash
mcpo --port 8000 --api-key "top-secret" --server-type "sse" --headers '{"Authorization": "Bearer token", "X-Custom-Header": "value"}' -- http://127.0.0.1:8001/sse
```

*   `--headers`:  A JSON string containing the headers to send with the SSE request.

**Streamable HTTP-Compatible MCP Server:**

If your MCP server uses Streamable HTTP:

```bash
mcpo --port 8000 --api-key "top-secret" --server-type "streamable_http" -- http://127.0.0.1:8002/mcp
```

*   `--server-type "streamable_http"`: Specifies that the MCP server uses Streamable HTTP.
*   `http://127.0.0.1:8002/mcp`: The URL of your Streamable HTTP server.

**Using a Configuration File:**

For managing multiple MCP servers, you can use a configuration file in the Claude Desktop format.

1.  **Create a `config.json` file (example):**

    ```json
    {
      "mcpServers": {
        "memory": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-memory"]
        },
        "time": {
          "command": "uvx",
          "args": ["mcp-server-time", "--local-timezone=America/New_York"]
        },
        "mcp_sse": {
          "type": "sse",
          "url": "http://127.0.0.1:8001/sse",
          "headers": {
            "Authorization": "Bearer token",
            "X-Custom-Header": "value"
          }
        },
        "mcp_streamable_http": {
          "type": "streamable_http",
          "url": "http://127.0.0.1:8002/mcp"
        }
      }
    }
    ```

2.  **Run `mcpo` with the `--config` option:**

    ```bash
    mcpo --config /path/to/config.json --api-key "top-secret"
    ```

    *   `--config`: Specifies the path to your `config.json` file.

**Accessing the OpenAPI Schema:**

Once `mcpo` is running, you can access the auto-generated OpenAPI schema and interactive documentation at `http://localhost:<port>/docs` (e.g., `http://localhost:8000/docs`). When using a config file, each tool will have its own endpoint and documentation (e.g., `http://localhost:8000/memory/docs`, `http://localhost:8000/time/docs`).

### Environment Variables

While not explicitly required, you can use environment variables for sensitive information like the API key.  For example:

```bash
export MCPO_API_KEY="your-secret-api-key"
mcpo --port 8000 --api-key "$MCPO_API_KEY" -- your_mcp_server_command
```

This prevents the API key from being directly visible in your command history.

## Tools

## Available Tools

mcpo provides the following features to expose MCP tools as OpenAPI-compatible HTTP servers:

*   **OpenAPI Proxy:** Exposes any MCP server command as a RESTful API endpoint, instantly making it compatible with LLM agents and applications expecting OpenAPI servers.
    *   Usage: `mcpo --port 8000 --api-key "top-secret" -- your_mcp_server_command`

*   **Automatic OpenAPI Documentation:** Auto-generates interactive documentation for each exposed MCP tool, accessible via a `/docs` endpoint. No configuration is required.
    *   Usage: Access the documentation at `http://localhost:8000/docs` after running mcpo.

*   **Security and Stability:** Adds security, stability, and scalability to MCP tools using standard web technologies like HTTP and API keys.

*   **SSE (Server-Sent Events) Support:** Allows proxying MCP servers that communicate via SSE.
    *   Usage: `mcpo --port 8000 --api-key "top-secret" --server-type "sse" -- http://127.0.0.1:8001/sse`
    *   Headers can be provided: `mcpo --port 8000 --api-key "top-secret" --server-type "sse" --headers '{"Authorization": "Bearer token", "X-Custom-Header": "value"}' -- http://127.0.0.1:8001/sse`

*   **Streamable HTTP Support:** Allows proxying MCP servers that communicate via Streamable HTTP.
    *   Usage: `mcpo --port 8000 --api-key "top-secret" --server-type "streamable_http" -- http://127.0.0.1:8002/mcp`

*   **Configuration File Support:** Allows serving multiple MCP tools via a single configuration file (Claude Desktop format).
    *   Usage: `mcpo --config /path/to/config.json`
    *   Example config.json:
        ```json
        {
          "mcpServers": {
            "memory": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-memory"]
            },
            "time": {
              "command": "uvx",
              "args": ["mcp-server-time", "--local-timezone=America/New_York"]
            },
            "mcp_sse": {
              "type": "sse", // Explicitly define type
              "url": "http://127.0.0.1:8001/sse",
              "headers": {
                "Authorization": "Bearer token",
                "X-Custom-Header": "value"
              }
            },
            "mcp_streamable_http": {
              "type": "streamable_http",
              "url": "http://127.0.0.1:8002/mcp"
            } // Streamable HTTP MCP Server
          }
        }
        ```
        Each tool is accessible under its own unique route, e.g.: `http://localhost:8000/memory`, `http://localhost:8000/time` with dedicated OpenAPI schema and proxy handler. Access full schema UI at: `http://localhost:8000/<tool>/docs` (e.g. `/memory/docs`, `/time/docs`)

*   **Docker Support:** Can be run in a Docker container for easy deployment and portability.
    *   Usage: `docker run -p 8000:8000 ghcr.io/open-webui/mcpo:main --api-key "top-secret" -- your_mcp_server_command`