1P
Developer Tools

1Panel MCP Server for Remote Panel Control

Control remote panels with a lightweight MCP server for seamless 1Panel interaction, real-time monitoring, and secure API-driven management.

View on GitHub
Quick Install
npx -y @1Panel-dev/mcp-1panel

Overview

1Panel MCP Server is a small, API-driven server that enables remote control and monitoring of 1Panel display panels. It exposes HTTP endpoints and real-time streams so external systems (CI/CD, monitoring, automation scripts) can programmatically update panel content, query state, and receive event updates without direct access to the panel hardware or browser UI.

Designed to be lightweight and easy to deploy, the MCP server sits between your orchestration or automation tooling and deployed panels. It provides a predictable API surface for secure, auditable control and includes health checks and metrics for integration with standard observability stacks.

Features

  • Lightweight HTTP/WS server for panel management and event streaming
  • REST API to list panels, read state, and issue commands
  • WebSocket/event stream for real-time updates and notifications
  • Token- or secret-based authentication and configurable TLS
  • Docker-friendly: run as a container or standalone binary
  • Health, metrics, and logging hooks for monitoring and alerting
  • Configurable via environment variables or a configuration file
  • Designed to integrate with CI/CD, automation platforms, and dashboards

Installation / Configuration

Prerequisites: Docker or a Go toolchain (if building from source).

Clone and build from source (Go):

git clone https://github.com/1Panel-dev/mcp-1panel.git
cd mcp-1panel
# build the server (example; actual build target may vary)
go build -o mcp-server ./cmd/mcp-server
./mcp-server --config ./config.yaml

Build and run with Docker:

# build locally
docker build -t mcp-1panel .

# run with environment variables and port mapping
docker run -d \
  --name mcp-1panel \
  -p 8080:8080 \
  -e MCP_BIND_ADDR="0.0.0.0:8080" \
  -e MCP_API_SECRET="replace-with-secret" \
  -e MCP_LOG_LEVEL="info" \
  mcp-1panel:latest

Example environment variables (common configuration options):

VariableDefaultDescription
MCP_BIND_ADDR0.0.0.0:8080Address and port to bind the server
MCP_API_SECRET(required)Shared secret or token for API authentication
MCP_TLS_CERT(empty)Path to TLS certificate (enable TLS if set)
MCP_TLS_KEY(empty)Path to TLS key
MCP_LOG_LEVELinfoLog verbosity: debug/info/warn/error
MCP_CONFIG_FILEconfig.yamlPath to YAML configuration file

Example YAML config snippet:

server:
  bind: "0.0.0.0:8080"
  tls:
    cert: "/etc/mcp/cert.pem"
    key: "/etc/mcp/key.pem"

auth:
  api_secret: "replace-with-secret"

panels:
  default_ttl: 300

Available Resources

The MCP server exposes a small set of HTTP endpoints and a WebSocket for live updates. Exact paths may vary by release; the examples below illustrate the typical API surface.

Endpoints (examples)

  • GET /api/v1/panels
    • List registered panels and their status.
  • GET /api/v1/panels/{id}
    • Retrieve a single panel’s metadata and last-known state.
  • POST /api/v1/panels/{id}/control
    • Send a control command (e.g., change content, update brightness).
    • Payload example:
      {
  "action": "set_content",
  "content": "<html>...</html>",
  "ttl": 60
}
  • GET /ws
    • WebSocket endpoint for real-time events: panel-connected, panel-disconnected, state-changed.
  • GET /metrics
    • Prometheus-compatible metrics (if enabled).
  • GET /health
    • Simple healthcheck for orchestration probes.

Authentication

  • Pass the API secret in an Authorization header or via a configured header:
    Authorization: Bearer <MCP_API_SECRET>

Real-time subscription example (wscat)

wscat -c "ws://localhost:8080/ws?token=replace-with-secret"
# receives JSON event messages as panels change state

Simple cURL to update a panel:

curl -X POST http://localhost:8080/api/v1/panels/panel-123/control \
  -H "Authorization: Bearer replace-with-secret" \
  -H "Content-Type: application/json" \
  -d '{"action":"set_content","content":"<h1>Build: green</h1>","ttl":120}'

Use Cases

  • Continuous integration dashboards: Automatically update panel displays with build and test status after each pipeline run using the REST API.
  • Operations rooms and NOC displays: Push alerts and status messages to wall panels in real time via WebSocket events or direct control calls.
  • Remote kiosk/content management: Change content, schedule updates, or change brightness and system settings remotely from an orchestration service.
  • Automated maintenance and diagnostics: Query panel state and recent events to implement remote health checks, restart routines, or trigger alerts.
  • Multi-tenant panel fleets: Integrate MCP into a management plane that enforces access control and audit logs while providing a common API for different clients.

For code, issue tracking, or to contribute, see the project repository on GitHub: https

Tags:developer-tools