Content
[English](README.md) | [Русский](README_RU.md)
# MCPO Control Panel
[DeepWiki](https://deepwiki.com/daswer123/mcpo-control-panel)
A web-based control panel designed to simplify the management of [MCP-to-OpenAPI (`mcpo`)](https://github.com/open-webui/mcpo) instances and their server configurations. It provides a user-friendly UI and an API for interacting with `mcpo`.
## Demo
https://github.com/user-attachments/assets/dc3f11de-82f6-42ee-a72f-7181c9af0f45
## Key Features
* **Server Definition Management:**
* Create, Read, Update, and Delete server definitions (for `stdio`, `sse`, `streamable_http` types).
* Easily toggle servers as enabled/disabled for inclusion in the `mcpo` configuration.
* Intuitive forms for specifying commands, arguments, environment variables, and URLs.
* **Bulk Server Operations:**
* Add multiple server definitions at once by pasting JSON content.
* Supports various JSON formats (object with `mcpServers`, direct name-to-config map, list of server objects).
* Two-step bulk add process:
1. **Analyze:** Preview valid new servers, existing ones, and invalid entries from your JSON.
2. **Confirm:** Add only the validated new servers to the database.
* Automatic de-adaptation of Windows-specific commands (e.g., `cmd /c npx ...` -> `npx ...`).
* **MCPO Process Control:**
* Start, stop, and restart the `mcpo` process directly from the UI.
* View the real-time status of the `mcpo` process (Running, Stopped, Error).
* "Apply and Restart" functionality: Generates the `mcpo` configuration from current server definitions and then restarts `mcpo`.
* **Log Viewing:**
* Display the latest logs from the `mcpo` process log file.
* Configurable auto-refresh for logs.
* Manual refresh and auto-scroll options.
* **MCPO Settings Configuration:**
* Manage `mcpo` startup parameters (port, API key usage, config file path, log file path).
* Configure UI behavior (log refresh interval).
* Setup and manage health check parameters for `mcpo`.
* **Tool Aggregation & Viewing:**
* Dynamically fetches and displays a list of available tools (server paths and summaries) from a running `mcpo` instance by querying its OpenAPI specifications.
* Provides the base URL for constructing tool invocation links.
* **Health Checks & Auto-Restart:**
* Background health monitoring of the `mcpo` process using a built-in echo server.
* Configurable check interval, failure attempts, and retry delays.
* Optional automatic restart of `mcpo` if health checks fail consecutively.
* **Dynamic Configuration Generation:**
* Generates the `mcp_generated_config.json` file for `mcpo` based on enabled server definitions.
* Provides options to download the standard configuration or a Windows-adapted version (which wraps commands like `npx`, `uvx`, `docker` with `cmd /c ...`).
* **Modern Web UI:**
* Built with FastAPI, Jinja2 templates, and HTMX for a responsive and dynamic user experience.
* Utilizes Materialize CSS for styling.
* Persistent storage using an SQLite database (via SQLModel).
## Bundled Dependencies
To enhance reliability and enable deployment in offline or air-gapped environments, the MCPO Control Panel now bundles its core external frontend assets:
* **Materialize CSS & JavaScript**
* **Google Material Icons (font and CSS)**
* **htmx.org JavaScript**
This means the application does not rely on external CDNs for these resources, ensuring it remains fully functional without internet access after initial installation.
## Installation
It's recommended to use `uv` for installation if available, as it's generally faster.
### Method 1: Using uv (Recommended)
```bash
uv pip install mcpo-control-panel
```
### Method 2: Using pip (Traditional)
### Prerequisites
* Python 3.11 or higher.
```bash
pip install mcpo-control-panel
```
### Method 3: From Source (for development)
1. Clone the repository:
```bash
git clone https://github.com/daswer123/mcpo-control-panel.git
cd mcpo-control-panel
```
2. Install in editable mode (this will also install dependencies):
```bash
pip install -e .
```
### Method 4: Using Docker
You can also run the MCPO Control Panel using Docker. This is a convenient way to run the application in an isolated environment.
1. **Pull the ready-made image from Docker Hub:**
```bash
docker pull daswer123/mcpo-control-panel:latest
```
2. **Or build the Docker image yourself:**
Ensure you have [`Dockerfile`](Dockerfile:1) and [`docker-compose.yml`](docker-compose.yml:1) in your project root.
```bash
docker compose build
```
3. **Run the application using Docker Compose:**
```bash
docker compose up
```
This will start the MCPO Control Panel, and it will be accessible at `http://localhost:8083/ui` by default. The data will be persisted in a `./data` volume on your host machine.
You can customize the port and data directory in the [`docker-compose.yml`](docker-compose.yml:1) file if needed. Environment variables like `MCPO_MANAGER_HOST`, `MCPO_MANAGER_PORT`, and `MCPO_MANAGER_DATA_DIR` are also respected by the Docker container.
## Running the Application
Once installed, you can run the MCPO Control Panel.
**Using `python -m` (works with `pip` or `uv` installations):**
```bash
python -m mcpo_control_panel [OPTIONS]
```
**Using the installed script (if your Python scripts directory is in PATH):**
```bash
mcpo-control-panel [OPTIONS]
```
**Common Options:**
* `--host TEXT`: Host to bind the server to. (Default: `127.0.0.1`)
* Environment variable: `MCPO_MANAGER_HOST`
* `--port INTEGER`: Port to bind the server to. (Default: `8083`)
* Environment variable: `MCPO_MANAGER_PORT`
* `--workers INTEGER`: Number of Uvicorn workers. (Default: `1`)
* Environment variable: `MCPO_MANAGER_WORKERS`
* `--reload`: Enable auto-reload (for development).
* `--config-dir TEXT`: Directory for storing MCPO manager data (SQLite database, PID files, generated configs, settings).
* Default: `~/.mcpo_manager_data` (e.g., `C:\Users\YourUser\.mcpo_manager_data` on Windows or `/home/youruser/.mcpo_manager_data` on Linux).
* Environment variable: `MCPO_MANAGER_DATA_DIR`
**Example:**
```bash
python -m mcpo_control_panel --port 8083 --reload --config-dir "/path/to/my/mcpo-data"
```
**Example using `uvx` (executes the command in an isolated environment with the specified package):**
This is particularly useful for quick runs or testing without altering your global/current environment.
```bash
uvx --with mcpo-control-panel python -m mcpo_control_panel --host 0.0.0.0 --port 8934 --config-dir test
```
Or using environment variables:
```bash
export MCPO_MANAGER_PORT=8083
export MCPO_MANAGER_DATA_DIR="/path/to/my/mcpo-data"
python -m mcpo_control_panel --reload
```
The application will create the specified `--config-dir` if it doesn't exist. All application data, including the SQLite database (`mcp_manager_data.db`), settings file (`mcpo_manager_settings.json`), generated MCPO configuration (`mcp_generated_config.json`), and the `mcpo` process PID file, will be stored in this directory.
## Deployment Considerations
### Reverse Proxy Configuration
The MCPO Control Panel can be effectively run behind a reverse proxy. Here's how to configure it:
* **Proxy Headers:**
The application utilizes `ProxyHeadersMiddleware` from Uvicorn, which automatically respects `X-Forwarded-Proto` and `X-Forwarded-Host` headers. It's crucial to ensure your reverse proxy (e.g., Nginx, Apache, Traefik) is configured to pass these headers correctly.
* `X-Forwarded-Proto`: This header should reflect the protocol used by the client to connect to the proxy. If SSL termination occurs at the proxy (i.e., clients connect via HTTPS), the proxy must set `X-Forwarded-Proto: https`.
* `X-Forwarded-Host`: This header should reflect the original host requested by the client.
* **Base Path / Subpath (`root_path`):**
If the MCPO Control Panel is served under a specific subpath of a domain (e.g., `https://example.com/mcpmanager/`), you need to configure the `root_path` setting within the application.
* This setting is available on the "MCPO Settings" page in the UI.
* Set `root_path` to the subpath, including the leading slash (e.g., `/mcpmanager`).
* If the application is served at the root of a domain (e.g., `https://mcp.example.com/` or `http://localhost:8083/`), the `root_path` setting should be left empty (which is its default value).
The application uses this `root_path` to correctly generate all internal links and serve static assets.
**General Proxy Reminder:** Always ensure your reverse proxy is configured to set `X-Forwarded-Proto` and `X-Forwarded-Host` headers appropriately and to correctly proxy WebSocket connections if any part of the application were to use them (though MCPO Control Panel primarily uses HTTP/HTMX).
### Accessing the UI
Once the server is running, open your web browser and navigate to:
`http://<host>:<port>/ui`
For example, if running with default settings: `http://127.0.0.1:8083/ui`
## Configuration
Most configurations for the `mcpo` process itself (like its port, whether it uses an API key, log file paths) and for the UI (like log auto-refresh settings, health check parameters) are managed through the web interface on the "MCPO Settings" page.
These settings are saved to `mcpo_manager_settings.json` within the `MCPO_MANAGER_DATA_DIR_EFFECTIVE` (the directory specified by `--config-dir` or its default).
## License
This project is licensed under the MIT License
