Panelica MCP

Panelica MCP Server

Talk to your Panelica hosting panel in plain English.

Provision a domain, issue an SSL certificate, create a database, or restart a

service through Claude Desktop, Cursor, ChatGPT, or any other

Model Context Protocol client.

404 tools cover the entire External API surface — accounts, domains, DNS, SSL, email, MySQL, FTP, security, backups, server resources, and more.

Table of Contents

• How it works
• Requirements
• Install
• Option A — npm (recommended)
• Option B — Docker
• Option C — Build from source
• Configuration
• 1. Open the External API port
• 2. Generate an API key in the panel
• 3. Verify the credentials with curl
• Wire it into your MCP client
• Claude Code (one command)
• Claude Desktop
• Cursor
• OpenAI Codex CLI
• Continue.dev, Cline, Zed
• Generic stdio client
• Tool catalogue
• Example sessions
• Permission scopes
• Security model
• Troubleshooting
• Development
• Versioning & support
• License

How it works

+----------------+         stdio JSON-RPC          +-------------------+

| MCP client | <----------------------------> | panelica-mcp | | (Claude, ...) | | (this package) | +----------------+ +---------+---------+ | HTTPS + HMAC-SHA256| X-API-Key | X-Timestamp | X-Signature | v +------------------------------+------------------------------+ | https:// :8443/api/external/v1/... | | nginx reverse proxy on the panel host | | (TLS termination + path rewrite: /api/external/X -> /X) | +------------------------------+------------------------------+ | 127.0.0.1:3002 plain | v +----------------+-----------------+ | external-server (HMAC verify) | +----------------+-----------------+ | v +----------------+-----------------+ | Panelica panel + Linux services | +----------------------------------+

panelica-mcp is a thin, stateless adapter:

1. The MCP client launches the binary over stdio.
2. At startup the server fetches /v1/api-spec from your panel and builds the tool list from it (live catalogue, default). If the panel is unreachable it falls back to the bundled tools/tools.json snapshot. Set PANELICA_LIVE_SPEC=0 to always use the snapshot.
3. The client asks for the tool list and receives it — together with server instructions (how ids, scopes, response envelopes, errors and rate limits work, plus workflow recipes), generated from that same catalogue. See What the assistant knows.
4. When the client calls a tool, the server builds the corresponding HTTP request, signs it with HMAC-SHA256 using your local PANELICA_API_SECRET, and forwards it to the panel.
5. The HTTP response is returned to the client as the tool result. A failed call comes back as an explanation of what to do next (missing scope, wrong id, rate-limit reset…) rather than a bare status code.

No data is cached, no telemetry is emitted, and the secret never leaves the machine running the MCP server.

Requirements

• A running Panelica panel (version 1.0.193 or newer recommended; the External API surface is stable from 1.0.180+).
• HTTPS access to the panel UI on port 8443 from the machine that will run panelica-mcp. This is the same port you already use in the browser — no extra firewall change is required.
• One of the following runtimes on that machine:
• Node.js ≥ 20 for the npm install path
• Docker for the container path

You do not need to install anything on the panel host itself, and you do not need to open the internal port 3002 to the public internet.

Install

Pick whichever fits your MCP client setup. All three produce the same stdio binary; pick by which sandbox model you prefer.

Option A — npm (recommended)

npm install -g panelica-mcp

or run without installing (the MCP client launches npx for you):

npx -y panelica-mcp

The -y flag accepts npm's "install on first run" prompt non-interactively, which is what MCP clients need.

Option B — Docker

A pre-built image is published to GitHub Container Registry on every release:

docker pull ghcr.io/panelica/panelica-mcp:latest

Run it from an MCP client config:

{

"command": "docker", "args": [ "run", "--rm", "-i", "-e", "PANELICA_BASE_URL", "-e", "PANELICA_API_KEY", "-e", "PANELICA_API_SECRET", "ghcr.io/panelica/panelica-mcp:latest" ], "env": { "PANELICA_BASE_URL": "https://your-panel-host:8443/api/external", "PANELICA_API_KEY": "pk_...", "PANELICA_API_SECRET": "sk_..." } }

-i keeps stdin attached so the MCP client can talk to the container. --rm removes the container when the client disconnects.

Option C — Build from source

git clone https://github.com/Panelica/panelica-mcp.git

cd panelica-mcp npm install npm run build node dist/index.js # speaks MCP over stdio

To regenerate tools/tools.json from your panel's live API spec:

PANELICA_SPEC_URL="https://your-panel:8443/api/external/v1/api-spec" npm run rebuild-tools

Configuration

You need three values: a reachable base URL, an API key, and an API secret.

1. Pick the right base URL

Panelica's external-server process listens on 127.0.0.1:3002, and the panel's nginx on 8443 reverse-proxies /api/external/... to it. Nginx strips the /api/external prefix before forwarding, so the path the HMAC signature is computed over and the path the backend sees both end up as /v1/... — signatures match end-to-end without any extra knobs.

The right PANELICA_BASE_URL depends on where you run panelica-mcp:

You should not open port 3002 to the public internet. The default install binds it on all interfaces but expects it to be either firewalled or only reached through the 8443 reverse proxy.

Sanity-check the proxy from your machine:

curl -sk https://<panel-host>:8443/api/external/health

{"status":"ok"} or similar

If you get a TLS error, that is the panel's self-signed certificate — install a real cert on the panel (panel UI → Settings → SSL) rather than disabling verification client-side.

2. Generate an API key in the panel

1. Sign in to the panel as root or any account with permission to manage API keys.
2. Navigate to Settings → API Keys → Generate API Key.
3. Pick the scopes you want the MCP server to have. For a read-only assistant, *:read is enough (panel 1.0.528+; older panels need the individual :read scopes). For full automation grant *:write and *:delete too, or *:*. Every tool's description in this server lists the scopes it requires.
4. Copy both key (looks like pk_...) and secret (looks like sk_...). The secret is shown only once; store it in a password manager.

3. Verify the credentials with curl

Before you wire the MCP client up, prove the credentials work end-to-end:

export PANELICA_BASE_URL=https://your-panel-host:8443/api/external

export PANELICA_API_KEY=pk_xxxxxxxx export PANELICA_API_SECRET=sk_xxxxxxxx

TS=$(date +%s)

Signature is over METHOD + PATH + TIMESTAMP + BODY. The path is the

backend-visible path (/v1/...) — NOT the /api/external/ prefix that nginx

strips before forwarding. panelica-mcp does this automatically.

SIG=$(printf "GET/v1/api-keys${TS}" \ | openssl dgst -sha256 -hmac "$PANELICA_API_SECRET" -hex | awk '{print $2}')

curl -sk "$PANELICA_BASE_URL/v1/api-keys" \ -H "X-API-Key: $PANELICA_API_KEY" \ -H "X-Timestamp: $TS" \ -H "X-Signature: $SIG"

You should get back JSON listing your API keys. Common 401 responses:

4. Optional environment variables

Wire it into your MCP client

Claude Code (one command)

claude mcp add panelica \

-e PANELICA_BASE_URL=https://your-panel:8443/api/external \ -e PANELICA_API_KEY=pk_... \ -e PANELICA_API_SECRET=sk_... \ -- npx -y panelica-mcp

That's it — ask Claude Code to "list my domains" or "create a database for example.com" and it will drive the panel through the scoped API key.

Claude Desktop

Edit yo