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 logs, manage domains, create databases and monitor your server — all in natural language.

It covers the full Easypanel tRPC API with 37 tools, including safety guards that require explicit confirmation before any destructive action, and a context banner in every response so Claude always knows which project and service it is touching.

---

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:

{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "npx",
      "args": ["-y", "easypanel-mcp-server"],
      "env": {
        "EASYPANEL_URL": "https://your-panel.example.com",
        "EASYPANEL_TOKEN": "your-api-token"
      }
    }
  }
}

Option B — local build

git clone https://github.com/helbertparanhos/easypanel-mcp-server
cd easypanel-mcp-server
npm install && npm run build

{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/easypanel-mcp-server/dist/index.js"],
      "env": {
        "EASYPANEL_URL": "https://your-panel.example.com",
        "EASYPANEL_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor — reuse env vars across projects

In Cursor Settings → Tools & MCPs → Environment Variables, set:

• EASYPANEL_URL = https://your-panel.example.com
• EASYPANEL_TOKEN = your-api-token

Then your .cursor/mcp.json uses references that apply automatically to every project:

{
  "mcpServers": {
    "easypanel-mcp": {
      "command": "npx",
      "args": ["-y", "easypanel-mcp-server"],
      "env": {
        "EASYPANEL_URL": "${EASYPANEL_URL}",
        "EASYPANEL_TOKEN": "${EASYPANEL_TOKEN}"
      }
    }
  }
}

---

Adding context to a project

Place this in your project's CLAUDE.md so Claude knows which Easypanel project and service it should operate on by default:

## Easypanel
Project: `my-project` | Service: `my-api` | Branch: `main`
Repo: `owner/repo`

No folder copying needed — one MCP install serves all your projects.

---

Use cases

"Deploy my app" — Claude lists projects, inspects the current service, triggers deploy_service, then watches list_actions until it completes.

"Why is my service down?" — Claude calls get_service_error, get_service_logs and get_build_logs in sequence to diagnose.

"Add DATABASE_URL to staging" — Claude reads current env vars with get_env_vars, adds only the new key with set_env_var (never wipes others), and reminds you to redeploy.

"Create a Postgres database for this project" — Claude calls create_database, then inspect_database to return the connection string ready to use.

---

Available tools (37)

Category	Tools
Projects	list_projects, get_project, create_project, delete_project ⚠️
Services	inspect_service, create_service, rename_service ⚠️, destroy_service ⚠️, deploy_service, start_service, stop_service ⚠️, restart_service, get_service_error, get_service_notes, set_service_notes
Deploy / GitHub	set_source_github, set_source_image, enable_github_deploy, disable_github_deploy, list_actions, get_action
Env Vars	get_env_vars, set_env_var, delete_env_var ⚠️
Logs	get_service_logs, get_build_logs, get_system_stats
Domains	list_domains, add_domain, remove_domain ⚠️, set_primary_domain
Databases	create_database, inspect_database, destroy_database ⚠️
Monitoring	get_docker_stats, get_storage_stats, get_service_stats

⚠️ = requires confirm: "CONFIRMO" to execute.

Full tool descriptions with parameters are in llms.txt.

---

Safety features

Context banner

Every response that touches a specific project/service starts with:

[Contexto ativo: projeto="my-project" | serviço="my-api"]

Claude always knows what it is modifying before taking any action.

Confirmation guard

Destructive or production-impacting actions return BLOQUEADO until they receive confirm: "CONFIRMO":

{
  "status": "BLOQUEADO",
  "acao": "stop_service",
  "alvo": "serviço \"api\" (usuários perderão acesso)",
  "instrucao": "Para confirmar, passe o parâmetro: confirm: \"CONFIRMO\"",
  "aviso": "⚠️  Esta ação pode ser IRREVERSÍVEL. Confirme apenas se tiver certeza."
}

Safe env vars (read-modify-write)

set_env_var and delete_env_var read the current state, apply only the requested change, and write back. The Easypanel API replaces the entire env string on every update — without this protection it is easy to accidentally wipe all variables at once.

Sensitive value masking

get_env_vars masks values whose key matches *SECRET*, *PASSWORD*, *TOKEN*, *KEY* by default. Pass include_values: true to reveal.

---

Companion skill /ep

Install the workflow skill for guided deploy operations in Claude Code:

mkdir -p ~/.claude/skills/ep
cp skill/SKILL.md ~/.claude/skills/ep/SKILL.md

Then use /ep for an interactive deploy workflow without needing to remember tool names.

---

Known limitations

• No container exec — interactive console is not available via the Easypanel tRPC API (it uses WebSockets). Use get_service_logs and get_service_error for debugging.
• Log streaming — get_service_logs tries a REST endpoint; if unavailable, falls back to the last recorded service error.
• Auth scope — tools only work with app services (services.app.*). WordPress, Compose and Box service types are not covered.

---

Testing without Claude

npx @modelcontextprotocol/inspector dist/index.js

Opens a browser UI where you can call any tool manually and inspect the response.

---

Comparison with similar packages

Feature	easypanel-mcp-server	easypanel-mcp (sitp2k)
Total tools	37	~15
Auth method	Bearer token	Email + password
Confirmation guard	✅	❌
Safe env update (read-modify-write)	✅	❌
Sensitive value masking	✅	❌
Deploy action tracking	✅	❌
Companion Claude skill	✅	❌
GitHub deploy control	✅	Partial
Known limitations documented	✅	❌

---

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for how to add tools, report bugs and open PRs.

• Bug report
• Feature request

---

👤 Author

Created by Helbert Paranhos from Strat Academy.

If this project was useful, consider giving it a ⭐ and following Strat Academy for more AI automation content.

---

📄 License

MIT © Helbert Paranhos / Strat Academy

See LICENSE for details.