helbertparanhos/easypanel-mcp-server

> MCP Server for full Easypanel control via Claude Code, Cursor and Claude Desktop.
---
What is this
**easypanel-mcp-server** connects Claude Code, Cursor and Claude Desktop directly to your Easypanel instance — a modern Docker-based server control panel — through the Model Context Protocol.
Instead of switching between your editor and the Easypanel dashboard, you control everything from inside Claude: deploy from GitHub, update env vars, read live logs, exec into containers, manage domains, databases, volumes and ports, set resource limits, run Docker maintenance and monitor your server — all in natural language.
It maps the Easypanel API to **57 typed tools** across 15 categories, plus a single easypanel_raw escape hatch that reaches **any** of Easypanel's ~375 API operations for everything not covered by a dedicated tool. It speaks **all three API generations** — the tRPC API of panels ≤ 2.30, the RPC layer of 2.31–2.32, and the **public API introduced in Easypanel 2.33** — auto-detecting which one your panel uses. Every destructive action is gated behind an explicit confirmation, every response opens with a context banner so Claude always knows what it is touching, and an optional read-only mode lets you connect safely to a production panel.
📖 API reference: docs/easypanel-api.md — architecture, the API generations, confirmed operations mapped tool-by-tool, and how to discover new ones.
---
Compatibility
Easypanel changed its API twice in quick succession:
- **2.31** replaced the internal tRPC API with an RPC layer (/api/rpc/*). On panels ≥ 2.31, every v1.x call that carries parameters fails with 400 Input validation failed.
- **2.33** shipped a **documented public API** (/api/ , GET for reads, POST for writes) and stated that the old internal API *"may change without notice and should not be relied upon"*. v3 targets the public API on those panels.
| Your Easypanel version | Use |
|---|---|
| **any** (recommended) | easypanel-mcp-server@latest (**v3.x**) — auto-detects the generation, works on all three |
| **≤ 2.30.x** only, pinned | easypanel-mcp-server@legacy (**v1.3.x**) — frozen tRPC-only line, last validated against v2.30.1 |
v3 detects the generation with a single probe request on first call (cached) and logs the panel version to stderr. To skip detection, set EASYPANEL_API_FLAVOR to trpc (≤ 2.30), rpc (2.31–2.32) or public (≥ 2.33).
> **Upgrading from v2?** If you pinned EASYPANEL_API_FLAVOR=rpc to work around the 2.32 issues, **remove it** — otherwise the client stays on the internal API that Easypanel now declares unstable.
This MCP vs. Easypanel's built-in MCP
Easypanel 2.33 also ships its own MCP endpoint (/api/mcp, connection details next to your API key). It's a thin wrapper over the public API. This server is a different trade-off:
| | Easypanel built-in MCP | easypanel-mcp-server |
|---|---|---|
| Runtime container logs | — | ✅ via /ws/serviceLogs (no Loki/licence needed) |
| Exec inside a container | — | ✅ exec_in_container with destructive-command gate |
| Live Docker events | — | ✅ get_docker_events |
| Read-only mode | — | ✅ MCP_ACCESS_MODE=readonly blocks every write at the source |
| Confirmation gate on destructive ops | — | ✅ confirm: "CONFIRMO" |
| Secret redaction (list_users) | — | ✅ strips apiToken / twoFactorSecret |
| Env var read-modify-write | — | ✅ never clobbers other variables |
| Connection-string building | — | ✅ inspect_database |
| Coverage of every API operation | ✅ | ✅ via easypanel_raw |
| Zero install | ✅ | needs npx/node |
Using both at once is fine — they don't conflict.
---
Prerequisites
- Easypanel instance running and accessible
- API token — generate at **Easypanel → Settings → API → Generate Token**
- Node.js ≥ 18 and Claude Code, Cursor or Claude Desktop
---
Quick start
Option A — npx (no install needed)
Add .mcp.json to your project root:
Option B — local build
Cursor — reuse env vars across projects
In **Cursor Settings → Tools & MCPs → Environment Variables**, set: