easypanel-mcp-server

# easypanel-mcp-server > 用于通过Claude Code、Cursor和Claude Desktop实现Easypanel控制的全功能MCP服务器。 [](https://www.npmjs.com/package/easypanel-mcp-server) [](LICENSE) [](https://github.com/helbertparanhos/easypanel-mcp-server/stargazers) [](https://github.com/helbertparanhos/easypanel-mcp-server/network/members) [](https://github.com/helbertparanhos/easypanel-mcp-server/issues) [](https://glama.ai/mcp/servers/helbertparanhos/easypanel-mcp-server) [](https://www.typescriptlang.org/) [](https://nodejs.org/) [](https://modelcontextprotocol.io/) [](https://claude.ai/code) [](https://cursor.sh) [](https://claude.ai/download) [](https://www.instagram.com/helbertparanhos) [](https://www.youtube.com/@stratacademy) [](https://www.linkedin.com/in/helbert-paranhos/) [](https://buymeacoffee.com/helbertparanhos) [](https://stratacademy.com.br) --- ## 什么是 easypanel-mcp-server？ **easypanel-mcp-server** 通过模型上下文协议（MCP）将Claude Code、Cursor和Claude Desktop直接连接到您的Easypanel实例——一个现代的基于Docker的服务器控制面板。 不再需要在编辑器和Easypanel仪表板之间切换，您可以在Claude中控制所有内容：部署、更新环境变量、读取实时日志、执行容器操作、管理域名、数据库、卷和端口、设置资源限制、运行Docker维护任务和监控服务器——所有操作均通过自然语言进行。 它将Easypanel API映射到 **57个类型化工具**，涵盖15个类别，以及一个单独的`trpc_raw`逃生通道，可以访问Easypanel的所有约350个过程（40+命名空间）。它支持 **两种API生成** ——面板≤2.30的tRPC API和Easypanel 2.31中引入的新RPC层——并自动检测面板使用的是哪一个。每个破坏性操作都需要显式确认，每个响应都以上下文横幅开头，以便Claude始终知道它正在操作什么，并且可选的只读模式允许您安全地连接到生产面板。 📖 API 参考： [`docs/easypanel-api.md`](docs/easypanel-api.md) — 架构、43个命名空间、按工具映射的确认过程以及如何发现新过程。 --- ## 兼容性 **Easypanel 2.31 替换了其内部的tRPC API**，使用新的RPC层（`/api/rpc/*`，OpenAPI位于`/api/openapi.json`）。在面板≥ 2.31上，所有带有参数的v1.x调用都会失败，返回`400 输入验证失败`。 | 您的Easypanel版本 | 使用 | |---|---| | **任意** （推荐） | `easypanel-mcp-server@latest` （**v2.x**）——自动检测面板的API生成，适用于两者 | | **≤ 2.30.x** 仅限，已固定 | `easypanel-mcp-server@legacy` （**v1.3.x**）——冻结的仅tRPC线路，最后一次验证针对v2.30.1 | v2.x通过单个探测请求在第一次调用时检测生成（缓存）。要跳过检测，请设置 `EASYPANEL_API_FLAVOR=trpc` （≤ 2.30）或 `EASYPANEL_API_FLAVOR=rpc` （≥ 2.31）。 --- ## 先决条件 - Easypanel 实例正在运行且可访问 - API令牌 - 在 **Easypanel → 设置 → API → 生成令牌** 处生成 - Node.js ≥ 18 和 Claude Code、Cursor 或 Claude Desktop --- ## 快速开始 ### 选项A — npx（无需安装） 将 `.mcp.json` 添加到您的项目根目录： ```json { "mcpServers": { "easypanel-mcp": { "command": "npx", "args": ["-y", "easypanel-mcp-server"], "env": { "EASYPANEL_URL": "https://your-panel.example.com", "EASYPANEL_TOKEN": "your-api-token" } } } } ``` ### 选项B — 本地构建 ```bash git clone https://github.com/helbertparanhos/easypanel-mcp-server cd easypanel-mcp-server npm install && npm run build ``` ```json { "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 — 在项目之间重用环境变量 在 **Cursor 设置 → 工具和MCP → 环境变量** 中，设置： - `EASYPANEL_URL` = `https://your-panel.example.com` - `EASYPANEL_TOKEN` = `your-api-token` 然后，您的 `.cursor/mcp.json` 使用引用，这些引用会自动应用于每个项目： ```json { "mcpServers": { "easypanel-mcp": { "command": "npx", "args": ["-y", "easypanel-mcp-server"], "env": { "EASYPANEL_URL": "${EASYPANEL_URL}", "EASYPANEL_TOKEN": "${EASYPANEL_TOKEN}" } } } } ``` --- ## 环境变量 | 变量 | 必需 | 默认值 | 描述 | |----------|----------|---------|-------------| | `EASYPANEL_URL` | ✅ | — | 面板URL，无尾随斜杠（例如 `https://panel.example.com`） | | `EASYPANEL_TOKEN` | ✅ | — | API令牌（Easypanel → 设置 → API → 生成令牌） | | `MCP_ACCESS_MODE` | — | `full` | 设置为 `readonly` 以阻止 **所有** 写入（精选工具 **和** `trpc_raw`）。读取仍然可用 — 理想用于仅连接生产面板进行检查。 | | `EASYPANEL_API_FLAVOR` | — | _(自动)_ | 强制面板的API生成而不是自动检测：`trpc` （≤ 2.30）或 `rpc` （≥ 2.31）。别名：`legacy` / `modern`。 | | `EASYPANEL_RAW_DISABLED` | — | _(启用)_ | 设置为 `1` 以完全禁用 `trpc_raw` 出口。建议在MCP暴露给不受信任的内容时使用（提示注入风险），因为 `trpc_raw` 读取可以返回机密且 **不** 受只读模式保护。 | --- ## 添加项目上下文 将此添加到项目的 `CLAUDE.md` 中，以便Claude知道应默认操作哪个Easypanel项目和服务： ```markdown ## Easypanel 项目：`my-project` | 服务：`my-api` | 分支：`main` 仓库：`owner/repo` ``` 无需复制文件夹 — 一个MCP安装服务于所有项目。 --- ## 用例 > **"部署我的应用"** — Claude列出项目，检查当前服务，触发 `deploy_service`，然后监视 `list_actions` 直到它完成。 > **"为什么我的服务宕机了？"** — Claude 调用 `get_service_error`、`get_service_logs` 和 `get_build_logs`，并且可以 `exec_in_container` 检查文件/环境变量实时。 > **"将DATABASE_URL添加到 staging"** — Claude 读取当前环境变量，使用 `set_env_var` 添加新键（永远不会删除其他变量），并提醒您重新部署。 > **"给这个服务512MB和半个核心"** — Claude 调用 `set_service_resources` （读取当前限制并合并您的更改）并提醒您重启。 > **"持久化/app/data并暴露端口5432"** — Claude 调用 `create_mount` （命名卷）和 `create_port`，两者都在下一次部署时应用。 > **"我的磁盘已满"** — Claude 运行 `get_storage_stats`，然后 `cleanup_docker_images` 或 `prune_docker` （需确认）以释放空间。 > **"显示 Traefik 仪表板配置"** — 对于任何没有专用工具的内容，Claude 使用 `trpc_raw` 直接调用过程。 --- ## 可用工具（57个） | 类别 | 工具 | |----------|-------| | **项目** | `list_projects`、`get_project`、`create_project`、`delete_project` ⚠️ | | **服务** | `inspect_service`、`create_service`、`rename_service` ⚠️、`destroy_service` ⚠️、`deploy_service`、`start_service`、`stop_service` ⚠️、`restart_service`、`get_service_error`、`get_exposed_ports`、`get_service_notes`、`set_service_notes`、`set_service_resources` | | **部署 / GitHub** | `set_source_github`、`set_source_image`、`enable_github_deploy`、`disable_github_deploy`、`list_actions`、`get_action` | | **环境变量** | `get_env_vars`、`set_env_var`、`delete_env_var` ⚠️ | | **日志** | `get_service_logs`、`get_build_logs`、`get_system_stats` | | **容器** | `list_containers`、`exec_in_container` ⚠️、`get_docker_events` | | **域名** | `list_domains`、`add_domain`、`remove_domain` ⚠️、`set_primary_domain` | | **数据库** | `create_database`、`inspect_database`、`destroy_database` ⚠️ | | **卷 / 挂载** | `list_mounts`、`create_mount` ⚠️ | | **端口** | `list_ports`、`create_port` ⚠️ | | **Compose** | `create_compose`、`inspect_compose`、`deploy_compose` | | **监控** | `get_docker_stats`、`get_storage_stats`、`get_service_stats` | | **维护** | `prune_docker` ⚠️、`cleanup_docker_images` | | **服务器 / 基础设施** | `list_users`、`list_certificates`、`list_nodes`、`restart_panel` ⚠️、`reboot_server` ⚠️ | | **原始访问** | `trpc_raw` ⚠️ | ⚠️ = 需要 `confirm: "CONFIRMO"`。对于 `exec_in_container`、`create_mount`、`create_port` 和 `trpc_raw`，确认是 **有条件的**（仅适用于破坏性命令、敏感主机路径绑定、特权端口 `< 1024` 和分别写入变体）。 完整工具描述与参数在 [`llms.txt`](llms.txt) 中。对于底层API（两个版本），请参见 [`docs/easypanel-api.md`](docs/easypanel-api.md)。 ### `trpc_raw` — 访问约 350 个过程 涵盖每个Easypanel过程的专用工具并不实用，因此任何没有专用工具的内容都可以直接访问： ```jsonc // 读取（默认） { "procedure": "certificates.listCertificates" } { "procedure": "traefik.getDashboard" } // 写入 - 需要 isMutation:true AND confirm:"CONFIRMO" { "procedure": "branding.updateSettings", "input": { /* ... */ }, "isMutation": true, "confirm": "CONFIRMO" } ``` 有用的仅通过 `trpc_raw` 可达的命名空间： `traefik.*`、`branding.*`、`cloudflareTunnel.*`、`box.*`、`middlewares.*`、`notifications.*`、`volumeBackups.*`、`databaseBackups.*`、`wordpress.*`、`git.*`、`update.*`。 过程名称在两个API生成中使用点表示法 — 客户端翻译为正确的传输。面板 ≥ 2.31 还会根据面板自己的OpenAPI规范验证过程，失败关闭：`trpc_raw` 读取仅在规范将过程记录为查询时执行，因此写入不能绕过 `readonly` 模式或确认门槼。 --- ## 安全功能 ### 上下文横幅 每个响应触摸特定项目/服务时以以下内容开头： ``` [Contexto ativo: projeto="my-project" | serviço="my-api"] ``` Claude 始终知道它正在修改什么内容后再采取任何操作。 ### 确认保护 破坏性或影响生产的动作返回 `BLOQUEADO` 直到它们收到 `confirm: "CONFIRMO"`： ```json { "status": "BLOQUEADO", "acao": "stop_service", "target": "服务 \"api\" (用户将失去访问权限)", "instruction": "Para confirmar, passe o parâmetro: confirm: \"CONFIRMO\"", "aviso": "⚠️ 此操作可能是 **不可逆转的。仅在您确定时确认。" "警告": "⚠️" } ``` 此功能保护项目/服务删除、停止/重名、环境变量/*`。`trpc_raw` 读取不会绕过只读模式 — 原始读取可能会返回敏感数据；请在不受信任的环境中使用 `EASYPANEL_RAW_DISABLED=1`。`trpc_raw` 验证过程名称（命名空间/过程，无路径/查询注入），并要求 `CONFIRMO` 进行任何突变。设置 `EASYPANEL_RAW_DISABLED=1` 即可完全禁用它。 ### 机密隐藏 `list_users` 剥夺 `apiToken`、`twoFactorSecret` 和密码字段，然后返回 `id`、`email`、`admin`、`twoFactorEnabled` 和 `createdAt` — 只有这些字段可达。 ### 安全环境变量（读写修改） `set_env_var` 和 `delete_env_var` 读取当前状态，仅应用请求的更改，然后写回。 ### 敏感值掩盖 `get_env_vars` 默认情况下会隐藏键值匹配 `*SECRET*`、`*PASSWORD*`、`*TOKEN*`、`*KEY*` 的值。传递 `include_values: true` 以显示。 ### 令牌从不泄漏 HTTP 错误和 WebSocket 失败记录到 stderr 并以通用消息显示给模型 — bearer 令牌（发送到 WebSocket 查询字符串中，如 Easypanel 所需）永远不会到达模型上下文。 ### 输入验证 `projectName` / `serviceName` 在用于构建 Docker 服务名称或 WebSocket 查询之前会针对 `^[a-z0-9][a-z0-9_-]*$` 进行验证（防御深度防止目标混淆/参数注入）。端口验证为整数 `1–65535`；资源值必须是正数。 --- ## 伴侣技能 `/ep` 在Claude Code中安装引导部署操作的工作流技能： ```bash mkdir -p ~/.claude/skills/ep cp skill/SKILL.md ~/.claude/skills/ep/SKILL.md ``` 然后使用 `/ep` 进行交互式部署工作流程，无需记住工具名称。 --- ## 工作原理 Easypanel 面板通过 **tRPC** (`/api/trpc/<router>.<procedure>`) 与其后端通信，而不是公共 REST API。此服务器使用相同的端点： - **读取** 是 tRPC 查询；**写入** 是 tRPC 变更 — 请参见 [`docs/easypanel-api.md`](docs/easypanel-api.md)。 - **实时日志、容器执行和 Docker 事件** 使用面板的 WebSocket 通道（`/ws/serviceLogs`、`/ws/containerShell`、`/ws/dockerEvents`）— 与 UI 使用的通道相同 — 因此它们在没有授权日志（Loki）的情况下工作。 --- ## 已知限制 - **WordPress / Box 服务类型** — 未作为专用工具公开；通过 `trpc_raw` 访问它们（例如 `wordpress.inspectService`、`box.createService`）。 - **`trpc_raw` 读取绕过只读模式** — 只读阻止写入操作。只有原始读取可能会返回敏感数据；请在不受信任的环境中使用 `EASYPANEL_RAW_DISABLED=1`。 - **集群工具** — `list_nodes` 仅在单服务器设置中返回本地节点（无 Swarm 集群）。 - **Docker 事件** 是实时的，仅限于最近（无历史记录）— 空闲服务器可能会返回空窗口。 --- ## 无 Claude 测试 ```bash npx @modelcontextprotocol/inspector dist/index.js ``` 打开一个浏览器 UI，您可以在其中手动调用任意工具并检查响应。 --- ## 与类似软件包的比较 | 功能 | easypanel-mcp-server | easypanel-mcp (sitp2k) | |---------|---------------------|----------------------| | 精心策划的工具 | **57** | ~15 | | 对所有 ~347 个过程的原始访问 | ✅ (`trpc_raw`) | ❌ | | 认证方法 | Bearer 令牌 | 电子邮件 + 密码 | | 确认保护 | ✅ | ❌ | | 只读模式 | ✅ | ❌ | | 容器执行 + 实时日志（WebSocket） | ✅ | ❌ | | 卷 / 端口 / Compose / 资源 | ✅ | ❌ | | 服务器维护（清理 / 重启） | ✅ | ❌ | | 安全环境变量更新（读取-修改-写入） | ✅ | ❌ | | 机密隐藏和值掩盖 | ✅ | ❌ | | 配套 Claude 技能 | ✅ | ❌ | | 已知限制文档 | ✅ | ❌ | --- ## 🤝 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解如何添加工具、报告错误和开启 PR。 - [错误报告](.github/ISSUE_TEMPLATE/bug_report.md) - [功能请求](.github/ISSUE_TEMPLATE/feature_request.md) --- ## 👤 作者 由 **[Helbert Paranhos](https://github.com/helbertparanhos)** 创建，来自 **[Strat Academy](https://stratacademy.com.br)**。 [](https://www.instagram.com/helbertparanhos) [](https://www.youtube.com/@stratacademy) [](https://www.linkedin.com/in/helbert-paranhos/) [](https://buymeacoffee.com/helbertparanhos) 如果这个项目对您有帮助，请考虑给它一个 ⭐ 并关注 [Strat Academy](https://stratacademy.com.br)，获取更多 AI 自动化内容。 --- ## 📄 许可证 MIT © [Helbert Paranhos](https://github.com/helbertparanhos) / [Strat Academy](https://stratacademy.com.br) 请参阅 [LICENSE](LICENSE) 获取详细信息。