# helbertparanhos/easypanel-mcp-server [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/helbertparanhos/easypanel-mcp-server  
**GitHub Stars:** 4  
**npm Downloads (last month):** 982  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/helbertparanhos-easypanel-mcp-server

## Description
Full Easypanel control from Claude Code and Cursor — 37 tools for deployments, services, env vars, logs, domains, databases and monitoring. Safety guards require explicit confirmation for all destructive actions.

## Tools
Capabilities this server exposes over MCP:

- **list_projects** — Lista todos os projetos do Easypanel com seus serviços e status. Use para descobrir o que existe no painel antes de operar.
- **get_project** — Retorna detalhes completos de um projeto: lista de serviços, configurações e status atual.
- **create_project** — Cria um novo projeto no Easypanel.
- **delete_project** — ⚠️ DESTRUTIVO — Remove permanentemente o projeto e TODOS os seus serviços e dados. Irreversível. Requer confirm: "CONFIRMO".
- **inspect_service** — Retorna configuração completa de um serviço: source, env vars, deploy config, mounts, ports, domínios, recursos. Use SEMPRE antes de qualquer update para preservar o estado.
- **create_service** — Cria um novo serviço de app em um projeto. Após criar, configure a source com set_source_github ou set_source_image.
- **rename_service** — ⚠️ Renomeia ou move um serviço. Webhooks, DNS e referências internas que usam o nome antigo deixarão de funcionar. Requer confirm: "CONFIRMO".
- **destroy_service** — ⚠️ DESTRUTIVO — Remove permanentemente o serviço e seus dados. Irreversível. Requer confirm: "CONFIRMO".
- **deploy_service** — Dispara o deploy do serviço com a configuração atual. Usa o source configurado (GitHub, image, dockerfile). Funciona para serviços app E compose — detecta o tipo e roteia para o namespace certo (não precisa saber de antemão se é compose).
- **start_service** — Inicia um serviço que está parado. Funciona para app e compose (em compose, equivale a um redeploy/compose up).
- **stop_service** — ⚠️ PARA o serviço em produção. Usuários não conseguirão acessar enquanto parado. Requer confirm: "CONFIRMO".
- **restart_service** — Reinicia o serviço. Causa breve indisponibilidade. Funciona para app E compose — em compose, reinicia via redeploy (docker compose up recria os containers).
- **get_service_error** — Retorna o último erro registrado do serviço. Use para debugar falhas de deploy ou runtime.
- **get_exposed_ports** — Lista as portas expostas (publicadas no host) de um serviço. Use para descobrir em quais portas o serviço está acessível externamente.
- **get_service_notes** — Lê as notas/anotações salvas no serviço.
- **set_service_notes** — Salva notas/anotações no serviço (markdown suportado).
- **set_service_resources** — Define limites e reservas de CPU e memória do serviço. Envie só os campos que quer alterar — os omitidos mantêm o valor atual (0 = sem limite). Memória em MB, CPU em núcleos (0.5 = meio núcleo). Aplica no próximo deploy/restart.
- **set_source_github** — Configura a source do serviço para um repositório GitHub. O repo deve estar conectado no Easypanel (Settings > GitHub).
- **set_source_image** — Configura a source do serviço para uma imagem Docker.
- **enable_github_deploy** — Ativa o auto-deploy via GitHub: a cada push no branch configurado, um deploy é disparado automaticamente.
- **disable_github_deploy** — Desativa o auto-deploy via GitHub. Deploys precisarão ser disparados manualmente.
- **list_actions** — Lista as ações/jobs em execução ou recentes (deploys, builds, restarts). A lista global guarda apenas uma janela curta — passe projectName/serviceName para filtrar no servidor e não perder ações de um serviço específico.
- **get_action** — Retorna detalhes e logs de uma ação específica (deploy, build, etc).
- **get_env_vars** — Lista as variáveis de ambiente do serviço. Valores de variáveis sensíveis (KEY, SECRET, PASSWORD, TOKEN) são mascarados por padrão. Use include_values: true para ver os valores completos.
- **set_env_var** — Adiciona ou atualiza UMA variável de ambiente. Lê o estado atual antes de escrever — não apaga outras variáveis.
- **delete_env_var** — ⚠️ Remove UMA variável de ambiente. Lê estado atual antes de escrever. Requer confirm: "CONFIRMO".
- **get_service_logs** — Busca os logs do container de um serviço. Use para debugar erros em runtime. Retorna as últimas N linhas.
- **get_build_logs** — Retorna os logs de build/deploy do último action registrado para o serviço. Use para debugar falhas de build.
- **get_system_stats** — Retorna métricas do servidor: CPU, memória, disco, rede e uptime. Use para verificar saúde do servidor.
- **list_domains** — Lista todos os domínios configurados em um serviço.
- **add_domain** — Adiciona um domínio customizado ao serviço com HTTPS automático via Let's Encrypt.
- **remove_domain** — ⚠️ Remove permanentemente um domínio. O tráfego para esse host parará de funcionar. Requer confirm: "CONFIRMO".
- **set_primary_domain** — Define qual domínio é o primário (usado como URL principal do serviço).
- **create_database** — Cria um serviço de banco de dados (Postgres, MySQL, MariaDB, MongoDB ou Redis) em um projeto.
- **inspect_database** — Retorna detalhes do banco de dados: credenciais, porta exposta, connection string e status.
- **destroy_database** — ⚠️ DESTRUTIVO — Remove o banco de dados e TODOS os seus dados permanentemente. Irreversível. Requer confirm: "CONFIRMO".
- **get_docker_stats** — Retorna o estado das tasks Docker de cada serviço: réplicas em execução (actual) vs desejadas (desired). Use para ver rapidamente o que está no ar, escalado ou caído. Para CPU/memória de um serviço use get_service_stats.
- **get_storage_stats** — Retorna uso de armazenamento do servidor.
- **get_service_stats** — Retorna métricas de um serviço específico: CPU, memória e rede do container.
- **list_containers** — Lista os containers Docker em execução de um serviço (ID, nome, imagem, comando, status, portas). Use para descobrir o container antes de exec_in_container ou para checar se o serviço está rodando.
- **exec_in_container** — Executa um comando dentro do container de um serviço e retorna a saída (stdout/stderr). Use para debugar em runtime: inspecionar arquivos, checar variáveis, testar conectividade, rodar migrations, etc. Roda no primeiro container do serviço (ou no containerId informado). ⚠️ Executa comandos arbitrários — comandos potencialmente destrutivos (rm -rf, dd, mkfs, shutdown, kill, pipe para shell, etc.) exigem confirm: "CONFIRMO".
- **get_docker_events** — Captura eventos Docker do servidor em tempo real durante uma janela curta (~8s) — start, stop, kill, die, exec, health_status, etc. Use para investigar reinícios e falhas. Obs: só mostra eventos que ocorrem durante a captura (não há histórico); um servidor ocioso pode retornar vazio.
- **prune_docker** — Executa um "docker system prune" no servidor inteiro via Easypanel: remove containers parados, redes sem uso, cache de build e imagens não referenciadas para liberar espaço em disco. ⚠️ Ação destrutiva e de escopo GLOBAL (afeta todos os projetos do servidor, não um serviço específico) — exige confirm: "CONFIRMO". Use cleanup_docker_images para uma limpeza mais leve (só imagens não usadas).
- **cleanup_docker_images** — Remove do servidor apenas as imagens Docker não utilizadas (dangling/sem container), liberando espaço sem mexer em containers, redes ou volumes. Operação mais leve e segura que prune_docker — imagens podem ser recriadas em um novo deploy. Escopo global do servidor.
- **list_mounts** — Lista os volumes/mounts de um serviço (volumes nomeados, bind mounts e arquivos montados). Use para ver onde os dados persistentes do serviço estão.
- **create_mount** — Adiciona um volume/mount a um serviço para persistir dados entre deploys. Use type 'volume' para volume nomeado gerenciado, 'bind' para mapear um caminho do host. Aplica no próximo deploy.
- **list_ports** — Lista os mapeamentos de porta de um serviço (porta publicada no host → porta do container). Complementa get_exposed_ports com a configuração completa de portas. Use para ver o que está exposto e em qual protocolo.
- **create_port** — Publica uma porta de um serviço no host (port mapping), expondo-a externamente sem passar pelo proxy/domínio. Útil para TCP/UDP brutos (bancos, jogos, etc). Aplica no próximo deploy. ⚠️ Portas privilegiadas (publishedPort < 1024, ex: 80/443/22) exigem confirm: "CONFIRMO".
- **create_compose** — Cria um serviço do tipo Docker Compose em um projeto. Depois use set_compose_file (via easypanel_raw) ou o painel para definir o docker-compose, e deploy_compose para subir.
- **inspect_compose** — Retorna a configuração de um serviço Docker Compose: arquivo compose, env, source e estado. Use antes de qualquer alteração.
- **deploy_compose** — Dispara o deploy (docker compose up) de um serviço Compose com a configuração atual.
- **list_users** — Lista os usuários do painel Easypanel (admin, e-mails, papéis).
- **list_certificates** — Lista os certificados SSL/TLS gerenciados pelo Easypanel (domínios cobertos, emissor, validade). Use para auditar HTTPS e renovações.
- **list_nodes** — Lista os nós do cluster Docker Swarm gerenciado pelo Easypanel (manager/worker, status, disponibilidade). Em servidor único retorna apenas o nó local.
- **restart_panel** — ⚠️ Reinicia o próprio Easypanel. O painel/API ficam brevemente indisponíveis; os serviços hospedados continuam rodando. Requer confirm: "CONFIRMO".
- **reboot_server** — ⚠️ CRÍTICO — Reinicia o SERVIDOR inteiro (máquina host). TODOS os serviços e o painel ficam fora do ar até o boot completar. Use apenas em manutenção planejada. Requer confirm: "CONFIRMO".
- **easypanel_raw** — Chama diretamente qualquer operação da API do Easypanel (~375) não coberta pelas tools dedicadas. Use para recursos avançados: Traefik, branding, Cloudflare Tunnel, Box, WordPress, backups de volume/banco, notificações, storage providers, etc. Leitura (isMutation=false) é o padrão. ⚠️ Reads podem retornar dados sensíveis (env vars/secrets de qualquer projeto). Para escrita, passe isMutation:true E confirm:"CONFIRMO" — escritas arbitrárias pulam as proteções das tools curadas. Para descobrir os nomes disponíveis, leia GET <painel>/api/openapi.json.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `EASYPANEL_URL`, `EASYPANEL_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What helbertparanhos/easypanel-mcp-server MCP server does

The helbertparanhos/easypanel-mcp-server MCP server connects MCP-compatible clients to an Easypanel instance. It maps Easypanel operations to 57 typed tools grouped across 15 areas, covering common administration tasks such as deploying from GitHub, changing environment variables, viewing service logs, managing domains and databases, handling volumes and ports, adjusting resource limits, and monitoring the server.

The server also includes an `easypanel_raw` tool for operations that do not have a dedicated wrapper. Responses include a context banner so the client can identify the panel being accessed.

## How it works

The helbertparanhos/easypanel-mcp-server MCP server communicates with Easypanel using an API token. On its first request, it can probe the panel and cache the detected API generation. It supports the tRPC API used by panels up to version 2.30, the RPC layer used by versions 2.31 through 2.32, and the public API introduced in version 2.33 and later.

The API generation can be selected automatically or forced with `EASYPANEL_API_FLAVOR`. Valid values are `trpc`, `rpc`, and `public`; `legacy` and `modern` are also documented as aliases. A read-only mode blocks writes at the source, including writes attempted through `easypanel_raw`. Destructive actions additionally require the explicit confirmation value `CONFIRMO`.

## Setup and configuration

Install Node.js 18 or newer and make sure the Easypanel instance is reachable. Generate an API token in Easypanel under Settings, API, and Generate Token. The documented no-install configuration runs the package with npx:

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

`EASYPANEL_URL` should not include a trailing slash. Set `MCP_ACCESS_MODE` to `readonly` when the client should inspect a production panel without changing it. Set `EASYPANEL_RAW_DISABLED=1` to remove the raw API tool, which is recommended when untrusted content may reach the MCP client. Leave `EASYPANEL_API_FLAVOR` unset unless automatic detection should be overridden.

## Tools and capabilities

The documented tool coverage includes:

- Deployments and services, including GitHub-based deployment workflows.
- Environment variable updates that preserve variables not being changed.
- Runtime logs through the service logs WebSocket endpoint.
- Container command execution with a destructive-command confirmation gate.
- Domains, databases, connection-string inspection, volumes, ports, and resource limits.
- Docker maintenance, live Docker events, and server monitoring.
- User listing with `apiToken` and `twoFactorSecret` values removed from responses.

## Limitations and notes

The helbertparanhos/easypanel-mcp-server MCP server requires an accessible Easypanel installation, a valid API token, and Node.js 18 or newer. Its version compatibility depends on the panel's API generation; the current v3 line is documented for all three generations, while the legacy v1.3 line is intended only for Easypanel versions up to 2.30.x.

The raw tool provides broader coverage but may expose sensitive data in read responses, so disabling it can reduce prompt-injection risk. Easypanel 2.33 also provides its own MCP endpoint; this project is a separate client that adds features such as read-only enforcement, confirmation gates, runtime logs, and container execution.

_Full upstream README: https://allmcps.com/mcp/helbertparanhos-easypanel-mcp-server/readme_