Skip to main content
Glama

dpanel-mcp

DPanel 的 MCP (Model Context Protocol) 服务器。将 DPanel 的 Docker 管理能力暴露为 MCP 工具,供 AI Agent 调用。

独立项目,按 DPanel 版本对齐发布:dpanel-mcp 1.11.0 ↔ DPanel 1.11.x。仓库地址:GitHub leavrcn/dpanel-mcp。

参考 portainer/portainer-mcp 的架构设计(能力分级、脱敏、fail-closed 破坏性操作确认)。

架构

MCP Client (Claude/Cursor/Hermes...)
        │  stdio 或 streamable-http
        ▼
dpanel-mcp (Python + FastMCP)
   ├─ profiles.py   能力分级 read-only / read-write / admin
   ├─ redaction.py  敏感值脱敏(密码/token/secret)
   ├─ tools.py      80+ MCP 工具 → DPanel API
   └─ client.py     JWT 登录 + 自动续期
        │  HTTP POST /dpanel/api/*  (Authorization: Bearer JWT)
        ▼
DPanel (donknap/dpanel)
        │
        ▼
Docker Engine (docker.sock)

Related MCP server: EasyPanel MCP Server

快速开始

1. 环境变量

export DPANEL_HOST=http://127.0.0.1:8807        # DPanel 访问地址
export DPANEL_USERNAME=admin                    # DPanel 管理员用户名
export DPANEL_PASSWORD=your-password            # DPanel 密码
export DPANEL_MCP_PROFILE=read-write            # read-only | read-write | admin

2. stdio 模式(本地单用户)

uvx --from git+https://github.com/leavrcn/dpanel-mcp dpanel-mcp

Claude Desktop / Cursor 配置:

{
  "mcpServers": {
    "dpanel": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/leavrcn/dpanel-mcp", "dpanel-mcp"],
      "env": {
        "DPANEL_HOST": "http://127.0.0.1:8807",
        "DPANEL_USERNAME": "admin",
        "DPANEL_PASSWORD": "your-password"
      }
    }
  }
}

3. streamable-http 模式(容器/团队部署)

export DPANEL_MCP_TRANSPORT=streamable-http
export DPANEL_MCP_HTTP_HOST=0.0.0.0
export DPANEL_MCP_HTTP_PORT=8090
export DPANEL_MCP_AUTH_TOKEN=shared-secret     # 可选,门禁
uvx --from git+https://github.com/leavrcn/dpanel-mcp dpanel-mcp

客户端配置:{"url": "http://host:8090/mcp", "headers": {"Authorization": "Bearer shared-secret"}}

4. Docker 联合部署(推荐生产方式)

DPanel 与 dpanel-mcp 作为两个容器在同一网络运行,MCP 只通过 HTTP 访问 DPanel,无需挂载 docker.sock。

仓库根目录已提供联合部署示例 docker-compose.example.yml(内含 DPanel 1.11.x + dpanel-mcp 完整编排):

# 1. 拷贝并按需修改密码/token
cp docker-compose.example.yml docker-compose.yml
# 创建 .env 文件并填入实际值(DP_JWT_SECRET / DPANEL_ADMIN_PASSWORD / DPANEL_MCP_AUTH_TOKEN)

# 2. 启动
docker compose up -d

# 3. 首次启动需创建 DPanel founder 账号(免鉴权接口)
curl -s http://127.0.0.1:8807/dpanel/api/common/user/create-founder \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"你的强密码","confirmPassword":"你的强密码"}'

单独构建 MCP 镜像(开发/自改代码时):docker build -t dpanel-mcp:latest .

镜像发布渠道:

  • ghcr.io:ghcr.io/leavrcn/dpanel-mcp:1.11.0(双架构 amd64/arm64,compose 默认拉取此镜像)

  • 推送 v* tag 自动构建发布(GitHub Actions),也可在 Actions 页面手动触发

要点:

  • DPANEL_HOST 填 DPanel 的服务名 + 容器内部端口(如 http://dpanel:8080),不是宿主机映射端口

  • compose 里固定 DP_JWT_SECRET,DPanel 重启后 MCP 会话不失效(未固定时 DPanel 每次启动随机生成 secret,旧 token 全部作废;MCP 客户端有 401 自动重登兜底)

  • 镜像以非 root 用户(uid 10001)运行,内置 TCP 健康检查

  • DPANEL_MCP_AUTH_TOKEN 是 MCP 端点的访问门禁,务必换成强随机值

工具分组

分组

工具数

说明

system

5

系统信息、资源使用、配置、日志

env

5

Docker 环境(多主机)

container

14

容器列表/详情/统计/生命周期/删除

upgrade

4

容器升级检查/升级/忽略

backup

5

容器备份/恢复

compose

10

项目列表/部署/控制/日志/销毁

image

11

镜像列表/tag/删除/清理

image-build

6

镜像构建任务

network

8

网络列表/创建/连接/删除

volume

5

卷列表/创建/删除

explorer

10

文件管理(volume/container/docker 挂载点)

cron

8

计划任务(含模板)

store

5

应用商店

registry

4

镜像仓库

notice

3

通知(操作事件流水)

共 99 个工具。

能力分级

  • read-only:仅查询类工具(列表/详情/统计/日志)

  • read-write:+ 生命周期与创建(start/stop/restart/deploy/create)

  • admin:+ 破坏性操作(delete/prune/restore/kill),且必须显式传 confirm=true

破坏性操作 fail-closed:不传 confirm 直接拒绝,不执行。

脱敏

所有工具返回值经递归脱敏:键名命中 password/token/secret/key/credential 等 → ******;字符串中的 JWT 与 SECRET=value 形式的环境变量同样脱敏。

鉴权链

  1. MCP server 启动后用 DPanel 管理员账号登录(/common/user/login,autoLogin=true → 30 天 JWT)

  2. JWT 缓存,过期前 5 分钟自动重登

  3. 401 时透明重登一次

  4. streamable-http 模式下可加 DPANEL_MCP_AUTH_TOKEN 门禁(客户端需带 Bearer)

版本与兼容性

对齐 DPanel 1.11.x(版本号与 DPanel 一致)。所有路由与参数结构均已在真实 DPanel 1.11.0 容器上逐一验证(126 条路由探测 + compose 全生命周期端到端测试)。

DPanel 版本

兼容性

1.11.x

✅ 完全兼容(本版本目标)

1.9.x–1.10.x

⚠️ 部分路由已重命名(image-delete→delete、explorer 迁移至 common/、container-upgrade 独立模块),约 20 个工具不可用

≤1.8.x

❌ 未验证

DPanel API 变更时同步升版本。遇到 endpoint not found on DPanel 错误时,说明 DPanel 版本与本 MCP 不匹配。

Available Tools

99 tools
dpanel_compose_container_ctrlDpanel Compose Container CtrlC

Compose 项目控制:op ∈ start|stop|restart|pause|unpause|ls。

Inputs: id (required), op (required). Returns: result

dpanel_compose_createDpanel Compose CreateA

创建/更新 compose 项目。compose_type ∈ text|remoteUrl|outPath(storagePath/store 不可手动建)。 yaml 为完整 docker-compose 内容(text 类型)。传 id 为更新。返回项目 id。

Inputs: name (required), yaml (required), id, title, +2 more. Returns: result

dpanel_compose_deployDpanel Compose DeployC

部署/更新 compose 项目。id 为项目 id。deploy_service_name 可指定只部署部分服务。

Inputs: id (required), environment, remove_orphans, deploy_service_name. Returns: result

dpanel_compose_destroyDpanel Compose DestroyA

销毁 compose 项目(破坏性,需 confirm=true)。delete_data=true 同时删除项目记录; delete_path=true 删除 compose 文件目录。

Inputs: id (required), confirm, delete_data, delete_path, +2 more. Returns: result

dpanel_compose_get_from_gitDpanel Compose Get From GitC

从 Git 仓库拉取 compose 文件。

Inputs: uri (required), name (required). Returns: result

dpanel_compose_get_from_uriDpanel Compose Get From UriC

从 URL 拉取 compose 文件内容。

Inputs: uri (required). Returns: result

dpanel_compose_listDpanel Compose ListA

Compose 项目列表(含运行容器概览)。注意:dangling 项目 id=0,仅可查看。

Inputs: no named parameters. Returns: result

dpanel_compose_logDpanel Compose LogB

Compose 项目日志。line_total ∈ 50|100|200|500|1000|5000|-1。download=true 返回全量文本。

Inputs: id (required), download, line_total. Returns: result

dpanel_compose_taskDpanel Compose TaskB

Compose 项目详情与任务状态。id 为项目 id(数字字符串,列表返回)。

Inputs: id (required). Returns: result

dpanel_container_backup_createDpanel Container Backup CreateB

创建容器备份快照。id 为容器 ID。

Inputs: id (required). Returns: result

dpanel_container_backup_deleteDpanel Container Backup DeleteA

删除备份(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_container_backup_detailDpanel Container Backup DetailC

备份详情。id 为备份记录 id。

Inputs: id (required). Returns: result

dpanel_container_backup_listDpanel Container Backup ListC

容器备份列表。

Inputs: no named parameters. Returns: result

dpanel_container_backup_restoreDpanel Container Backup RestoreB

从备份恢复容器(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_container_check_portDpanel Container Check PortC

检查主机端口占用情况。

Inputs: port. Returns: result

dpanel_container_commitDpanel Container CommitC

将容器提交为新镜像。

Inputs: md5 (required), option (required). Returns: result

dpanel_container_copyDpanel Container CopyC

复制容器。copy_name 为新容器名。

Inputs: md5 (required), copy_name (required). Returns: result

dpanel_container_deleteDpanel Container DeleteB

删除容器(破坏性,需 confirm=true)。可选同时删除镜像/卷/链接。

Inputs: md5 (required), confirm, delete_link, delete_image, +1 more. Returns: result

dpanel_container_detailDpanel Container DetailB

容器详情。md5 为容器 ID(完整或前缀)。

Inputs: md5 (required). Returns: result

dpanel_container_exportDpanel Container ExportC

导出容器为镜像 tar。

Inputs: md5 (required). Returns: result

dpanel_container_listDpanel Container ListA

容器列表(含状态、镜像、名称、网络)。可按 md5(容器ID)或站点名过滤。注意:API 不分页,返回全量。

Inputs: md5, site_title. Returns: result

dpanel_container_processDpanel Container ProcessB

容器内进程列表。id 为容器 ID。

Inputs: id (required). Returns: result

dpanel_container_pruneDpanel Container PruneA

清理停止的容器(破坏性,需 confirm=true)。

Inputs: confirm. Returns: result

dpanel_container_statDpanel Container StatC

容器资源统计(CPU/内存/网络 IO)。id 为容器 ID。

Inputs: id (required). Returns: result

dpanel_container_statusDpanel Container StatusC

容器生命周期控制:operate ∈ start|stop|restart|pause|unpause。

Inputs: md5 (required), operate (required). Returns: result

dpanel_container_updateDpanel Container UpdateC

更新容器配置(重启策略/环境变量/端口等,option 结构与面板一致)。

Inputs: md5 (required), option (required). Returns: result

dpanel_container_upgradeDpanel Container UpgradeB

升级容器(拉新镜像并重建,保留配置)。image_tag 留空用原镜像。

Inputs: md5 (required), image_tag, enable_bak. Returns: result

dpanel_container_upgrade_checkDpanel Container Upgrade CheckC

检查单个容器镜像更新。container_id 为容器 ID。

Inputs: container_id (required). Returns: result

dpanel_container_upgrade_ignoreDpanel Container Upgrade IgnoreC

忽略容器升级(加入忽略清单)。

Inputs: md5 (required), image_id. Returns: result

dpanel_container_upgrade_listDpanel Container Upgrade ListB

容器升级检查列表(含可升级镜像 digest 对比)。

Inputs: no named parameters. Returns: result

dpanel_cron_createDpanel Cron CreateA

创建计划任务。trigger_type ∈ cron|event|manual。spec 为 cron 表达式(trigger=cron 时)。 option 结构参考 dpanel_cron_template 返回的模板。

Inputs: spec (required), title (required), option (required), trigger_type (required). Returns: result

dpanel_cron_deleteDpanel Cron DeleteA

删除计划任务(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_cron_detailDpanel Cron DetailC

计划任务详情。

Inputs: id (required). Returns: result

dpanel_cron_listDpanel Cron ListC

计划任务列表。

Inputs: no named parameters. Returns: result

dpanel_cron_log_listDpanel Cron Log ListD

计划任务执行日志。

Inputs: id (required). Returns: result

dpanel_cron_prune_logDpanel Cron Prune LogB

清理计划任务日志(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_cron_run_onceDpanel Cron Run OnceB

立即执行一次计划任务。

Inputs: id (required). Returns: result

dpanel_cron_templateDpanel Cron TemplateB

计划任务模板列表(10 个官方模板)。

Inputs: no named parameters. Returns: result

dpanel_env_createDpanel Env CreateC

创建 Docker 环境(连接远程 Docker host)。

Inputs: name (required), title (required), address (required). Returns: result

dpanel_env_deleteDpanel Env DeleteA

删除 Docker 环境(破坏性,需 confirm=true)。

Inputs: env_name (required), confirm. Returns: result

dpanel_env_detailDpanel Env DetailD

Docker 环境详情。

Inputs: name (required). Returns: result

dpanel_env_listDpanel Env ListA

列出 Docker 环境(多主机),含当前环境。

Inputs: no named parameters. Returns: result

dpanel_env_switchDpanel Env SwitchC

切换当前 Docker 环境(多主机)。

Inputs: env_name (required). Returns: result

dpanel_explorer_contentDpanel Explorer ContentC

读取文件内容。

Inputs: file (required), mount_point (required). Returns: result

dpanel_explorer_deleteDpanel Explorer DeleteC

删除文件(破坏性,需 confirm=true)。

Inputs: file_list (required), mount_point (required), confirm. Returns: result

dpanel_explorer_exportDpanel Explorer ExportD

导出文件(打包)。

Inputs: file_list (required), mount_point (required). Returns: result

dpanel_explorer_importDpanel Explorer ImportC

导入文件。file_list: [{name, path}]。

Inputs: dst_path (required), file_list (required), mount_point (required). Returns: result

dpanel_explorer_listDpanel Explorer ListC

文件列表。mount_point ∈ volume:<卷名> | container:<容器ID> | docker:<环境名>。

Inputs: mount_point (required), path. Returns: result

dpanel_explorer_mkdirDpanel Explorer MkdirC

新建目录。

Inputs: dst_path (required), mount_point (required). Returns: result

dpanel_explorer_path_sizeDpanel Explorer Path SizeC

目录大小统计。

Inputs: path (required), mount_point (required). Returns: result

dpanel_explorer_permissionDpanel Explorer PermissionC

修改文件权限/所有者。mod 如 644;owner 为用户名。

Inputs: file_list (required), mount_point (required), mod, owner. Returns: result

dpanel_explorer_statDpanel Explorer StatD

文件 stat 信息。

Inputs: path (required), mount_point (required). Returns: result

dpanel_explorer_unzipDpanel Explorer UnzipD

解压压缩文件。

Inputs: file (required), path (required), mount_point (required). Returns: result

dpanel_image_build_createDpanel Image Build CreateC

创建镜像构建任务(从 Dockerfile)。tags 为目标镜像 tag。

Inputs: tags (required), option. Returns: result

dpanel_image_build_deleteDpanel Image Build DeleteB

删除镜像构建任务(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_image_build_detailDpanel Image Build DetailD

镜像构建任务详情。

Inputs: id (required). Returns: result

dpanel_image_build_listDpanel Image Build ListC

镜像构建任务列表。

Inputs: no named parameters. Returns: result

dpanel_image_build_pruneDpanel Image Build PruneB

清理构建缓存(破坏性,需 confirm=true)。

Inputs: confirm. Returns: result

dpanel_image_build_runDpanel Image Build RunD

执行镜像构建任务。

Inputs: id (required). Returns: result

dpanel_image_deleteDpanel Image DeleteB

删除镜像(破坏性,需 confirm=true)。md5 为镜像 sha256 digest 数组。

Inputs: md5 (required), confirm. Returns: result

dpanel_image_detailDpanel Image DetailB

镜像详情。md5 为镜像 sha256 digest(如 sha256:abc123...)。

Inputs: md5 (required). Returns: result

dpanel_image_import_by_image_tarDpanel Image Import By Image TarB

导入镜像 tar(从 DPanel 存储目录)。

Inputs: no named parameters. Returns: result

dpanel_image_listDpanel Image ListC

镜像列表。

Inputs: no named parameters. Returns: result

dpanel_image_pruneDpanel Image PruneA

清理悬空镜像(破坏性,需 confirm=true)。

Inputs: confirm. Returns: result

dpanel_image_tag_addDpanel Image Tag AddB

为镜像添加 tag。md5 为镜像 digest,tag 形如 repo:tag。

Inputs: md5 (required), tag (required). Returns: result

dpanel_image_tag_deleteDpanel Image Tag DeleteA

删除镜像 tag(破坏性,需 confirm=true)。

Inputs: tag (required), confirm. Returns: result

dpanel_image_tag_push_batchDpanel Image Tag Push BatchC

批量推送镜像 tag 到远程仓库。

Inputs: md5 (required), registry_server_address (required). Returns: result

dpanel_image_tag_syncDpanel Image Tag SyncB

同步镜像 tag。sync_type ∈ pull|push。tag 形如 repo:tag。

Inputs: tag (required), sync_type. Returns: result

dpanel_log_listDpanel Log ListD

DPanel 系统日志列表。

Inputs: page, page_size. Returns: result

dpanel_network_connectDpanel Network ConnectC

将容器接入网络。

Inputs: name (required), container_name (required). Returns: result

dpanel_network_container_listDpanel Network Container ListC

网络上的容器列表。

Inputs: name (required). Returns: result

dpanel_network_createDpanel Network CreateC

创建网络。driver ∈ bridge|macvlan|ipvlan|overlay。

Inputs: name (required), driver. Returns: result

dpanel_network_deleteDpanel Network DeleteA

删除网络(破坏性,需 confirm=true)。

Inputs: name (required), confirm. Returns: result

dpanel_network_detailDpanel Network DetailD

网络详情。

Inputs: name (required). Returns: result

dpanel_network_disconnectDpanel Network DisconnectC

将容器从网络断开。

Inputs: name (required), container_name (required). Returns: result

dpanel_network_listDpanel Network ListC

网络列表。

Inputs: no named parameters. Returns: result

dpanel_network_pruneDpanel Network PruneA

清理未使用网络(破坏性,需 confirm=true)。

Inputs: confirm. Returns: result

dpanel_notice_deleteDpanel Notice DeleteB

删除通知(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_notice_listDpanel Notice ListC

通知列表(操作事件流水)。

Inputs: page, page_size. Returns: result

dpanel_notice_unreadDpanel Notice UnreadC

未读通知(action=new)。

Inputs: no named parameters. Returns: result

dpanel_registry_createDpanel Registry CreateC

添加镜像仓库。

Inputs: title (required), server_address (required), option. Returns: result

dpanel_registry_deleteDpanel Registry DeleteA

删除镜像仓库(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_registry_detailDpanel Registry DetailC

镜像仓库详情。

Inputs: id (required). Returns: result

dpanel_registry_listDpanel Registry ListC

镜像仓库列表。

Inputs: no named parameters. Returns: result

dpanel_setting_getDpanel Setting GetC

读取 DPanel 配置项。group_name 如 setting;name 如 DPanelInfo/docker。

Inputs: name (required), group_name (required). Returns: result

dpanel_store_createDpanel Store CreateC

添加应用商店源。

Inputs: url (required), apps (required), name (required), title (required), +1 more. Returns: result

dpanel_store_deleteDpanel Store DeleteB

删除应用商店源(破坏性,需 confirm=true)。

Inputs: id (required), confirm. Returns: result

dpanel_store_deployDpanel Store DeployC

从应用商店部署应用。store_id 为商店应用 id。

Inputs: option (required), store_id (required). Returns: result

dpanel_store_listDpanel Store ListC

应用商店应用列表。

Inputs: no named parameters. Returns: result

dpanel_store_syncDpanel Store SyncD

同步应用商店数据。

Inputs: url (required), name (required), store_type (required). Returns: result

dpanel_system_infoDpanel System InfoA

DPanel 系统信息:版本、运行环境、Docker 环境状态、数据挂载。

Inputs: no named parameters. Returns: result

dpanel_system_stat_listDpanel System Stat ListC

DPanel 多主机统计列表。

Inputs: no named parameters. Returns: result

dpanel_system_usageDpanel System UsageB

DPanel 所在主机资源使用情况(CPU/内存/磁盘/面板占用)。

Inputs: no named parameters. Returns: result

dpanel_volume_createDpanel Volume CreateD

创建卷。

Inputs: name (required), driver. Returns: result

dpanel_volume_deleteDpanel Volume DeleteA

删除卷(破坏性,需 confirm=true)。name 为卷名数组。

Inputs: name (required), confirm. Returns: result

dpanel_volume_detailDpanel Volume DetailD

卷详情。

Inputs: name (required). Returns: result

dpanel_volume_listDpanel Volume ListB

卷列表(含使用状态)。

Inputs: no named parameters. Returns: result

dpanel_volume_pruneDpanel Volume PruneA

清理未使用卷(破坏性,需 confirm=true)。

Inputs: confirm. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.4/5.0

    Scored across 99 tools

    Disambiguation4/5

    Tools are mostly separated by dpanel_<domain>_<action>, and descriptions make the intended operation clear. A few pairs still overlap, such as compose_create vs compose_deploy, image_tag_sync vs image_tag_push_batch, and container_upgrade_list/check/upgrade, so some care is needed during selection.

    Naming Consistency4/5

    All names use the dpanel_ prefix and snake_case, with a predictable domain-action pattern. Minor deviations exist, including noun-only names like system_info and container_status, and varied action placement like get_from_uri, but there is no chaotic convention mixing.

    Tool Count1/5

    99 tools far exceeds the 50+ extreme-mismatch threshold for an MCP tool set. Even for a broad Docker panel domain, this creates a very high selection and maintenance burden.

    Completeness3/5

    Coverage is broad across containers, compose, images, networks, volumes, files, cron, store, registry, system, and notices, including lifecycle, backup, and upgrade operations. However, common Docker operations like container logs and exec are absent, and settings/cron update operations are missing.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI assistants to interact with Docker containers through safe, permission-controlled access to inspect, manage, and diagnose containers, images, and compose services with built-in timeouts and AI-powered analysis.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to manage infrastructure and deploy Docker services through EasyPanel using natural language commands. It supports full lifecycle management of services, deployments, and networks while facilitating automated scaling and assisted debugging.
      29
      5
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to manage Docker containers, images, Compose stacks, health checks, and logs through a unified MCP interface, ensuring containers stay running with self-healing capabilities.
      31
      143 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to manage Docker containers through a secure MCP interface, supporting container lifecycle operations, log inspection, resource monitoring, and system diagnostics with role-based access control.
      3
      MIT