easypanel-mcp-server 是一个面向 Easypanel 的 MCP 服务器，由 Helbert Paranhos / Strat Academy 创建。它通过 Model Context Protocol 把 Claude Code、Cursor 和 Claude Desktop 直接连到 Easypanel 实例——一个基于 Docker 的现代服务器控制面板。目标是让用户不用在编辑器和 Easypanel 仪表盘之间来回切换，而是在 Claude 内以自然语言完成全部控制。
用途与定位 它把 Easypanel API 映射为 57 个带类型的工具，分布在 15 个类别，并提供一个 easypanel_raw 逃生通道，可触达 Easypanel 约 375 个 API 操作中未被专用工具覆盖的部分。它支持全部三代 API：面板 2.30 及以下的 tRPC API、2.31–2.32 的 RPC 层，以及 Easypanel 2.33 引入的公开 API，并会自动检测面板属于哪一代。
主要能力 可用自然语言完成：从 GitHub 部署、更新环境变量、读取实时日志、exec 进入容器、管理域名、数据库、卷和端口、设置资源限制、运行 Docker 维护以及监控服务器。具体示例包括：让 Claude 列出项目、检查当前服务、触发 deploy_service 并观察 list_actions 直到完成；调用 get_service_error、get_service_logs 和 get_build_logs 排查服务故障，并用 exec_in_container 实时检查文件或环境；用 get_env_vars 读取现有环境变量、用 set_env_var 只添加新键（不会清空其他变量）并提醒重新部署；用 set_service_resources 读取当前限制并合并修改；用 create_mount 创建命名卷、create_port 暴露端口；用 get_storage_stats 后再用 cleanup_docker_images 或 prune_docker 回收空间；对没有专用工具的功能用 easypanel_raw 直接调用过程。
使用方式 前置要求：已运行且可访问的 Easypanel 实例；在 Easypanel → Settings → API → Generate Token 生成 API 令牌；Node.js ≥ 18 以及 Claude Code、Cursor 或 Claude Desktop。安装方式有两种：方式 A 使用 npx（无需安装），在项目根目录添加 .mcp.json；方式 B 本地构建。Cursor 可在 Settings → Tools & MCPs → Environment Variables 中设置 EASYPANEL_URL 和 EASYPANEL_TOKEN 以跨项目复用环境变量。可在项目的 CLAUDE.md 中写入默认项目和服务，让 Claude 知道默认操作对象。无需复制文件夹，一次 MCP 安装即可服务所有项目。另提供配套技能 /ep，安装后可用 /ep 进行交互式部署工作流。
API 版本与兼容性 Easypanel 在短时间内两次更改了 API。2.31 用 RPC 层（/api/rpc/*）替换了内部 tRPC API，在 ≥ 2.31 的面板上，所有带参数的 v1.x 调用会以 400 Input validation failed 失败。2.33 发布了有文档的公开 API（/api/<operation>，GET 读、POST 写），并声明旧内部 API 可能随时更改、不应依赖。v3 在这些面板上针对公开 API。v3 在首次调用时用单个探测请求检测代次（缓存）并将面板版本记录到 stderr。可通过设置 EASYPANEL_API_FLAVOR 为 trpc、rpc 或 public 跳过检测。从 v2 升级时，如果曾固定 EASYPANEL_API_FLAVOR=rpc 以绕过 2.32 问题，应移除它。
与 Easypanel 内置 MCP 的对比 Easypanel 2.33 也自带 MCP 端点（/api/mcp），是公开 API 的薄封装。本项目是另一种取舍。两者同时使用没有问题，不会冲突。
安全特性 每个涉及特定项目或服务的响应都以上下文横幅开头；破坏性或影响生产的操作会返回 BLOQUEADO，直到收到 confirm: "CONFIRMO"；设置 MCP_ACCESS_MODE=readonly 可在源头（client.mutate）阻止所有写入，覆盖精选工具和 easypanel_raw，读取仍可用；easypanel_raw 会校验操作名（扁平或 namespace.procedure，无路径或查询注入），要求输入为对象（≤ 50KB），并对任何变更要求 CONFIRMO，设置 EASYPANEL_RAW_DISABLED=1 可完全关闭；list_users 会剥离 apiToken、twoFactorSecret 和 password 字段；set_env_var 和 delete_env_var 采用读-改-写，防止因 Easypanel API 每次更新都替换整个 env 字符串而意外清空全部变量；get_env_vars 默认对匹配 SECRET、PASSWORD、TOKEN、KEY 的键做掩码，可用 include_values: true 显示；HTTP 错误和 WebSocket 失败记录到 stderr，向模型暴露通用消息，bearer 令牌不会进入模型上下文；projectName 和 serviceName 在用于构建 Docker 服务名或 WebSocket 查询前按 ^[a-z0-9][a-z0-9_-]*$ 校验，端口校验为 1–65535 的整数，资源值必须为正数。
实现说明 Easypanel 面板通过 tRPC（/api/trpc/<router>.<procedure>）与其后端通信，而非公开 REST API，本服务器使用相同端点。读取是 tRPC 查询，写入是 tRPC 变更。实时日志、容器 exec 和 Docker 事件使用面板的 WebSocket 通道（/ws/serviceLogs、/ws/containerShell、/ws/dockerEvents），与 UI 使用的相同，因此无需许可的 Advanced Logs（Loki）也能工作。部分输入模式（挂载、端口、资源）已针对真实 Easypanel 验证并写入 API 参考。
已知限制 WordPress / Box 服务类型未暴露为专用工具，需通过 easypanel_raw（如 inspectWordPressService、createBoxService）访问。easypanel_raw 的读取会绕过只读模式，只读模式只阻止写入；原始读取可能返回敏感数据，在不可信环境中应使用 EASYPANEL_RAW_DISABLED=1。集群工具中 list_nodes 在单服务器设置（无 Swarm 集群）只返回本地节点。Docker 事件仅实时（无历史），空闲服务器可能返回空窗口。
测试与贡献 无需 Claude 的测试方式：打开浏览器 UI 手动调用任意工具并检查响应。项目欢迎贡献，见 CONTRIBUTING.md 了解如何添加工具、报告错误和提交 PR。项目采用 MIT 许可。
