DirectAdmin MCP 服务器

一个面向 DirectAdmin 的生产级 Model Context Protocol 控制平面。AI 代理（客服、所有者或应急系统管理员）与本进程通信；本进程与面板通信。每次调用都以命名哈希令牌进行身份验证，由配置文件（readonly / helpdesk / operator / break-glass）授权，可选确认，记录为结构化 JSON，进行速率限制，并在维护窗口之外拒绝。SSL 重新签发和 CSF/BFM 解锁是一等客服操作——它们不是全部功能。

预期布局是在代理旁边放置一个跳板主机（而不是在每个 DA 服务器上安装）：为健谈的代理提供只读监听器，为允许的变更提供写入监听器。集群事实（CloudLinux、配置文件）存储在该跳板机器上的 inventory.json 中。

它覆盖 DirectAdmin 新版 JSON API（来自官方 swagger 的 320 个操作）以及新版 API 仍无法替代的旧版 CMD_API_* 管理员调用（创建用户、DNS、备份、BFM）。

在将模型指向生产环境之前，请阅读 docs/agent.md 和 docs/tokens.md。

┌──────────────┐     MCP (stdio / SSE)     ┌──────────────────┐     HTTPS      ┌─────────────┐
│  Claude /    │ ─────────────────────────► │  directadmin-mcp │ ─────────────► │ DirectAdmin │
│  Cursor /    │                            │  confirm=true    │  Basic+key    │  :2222/api  │
│  any MCP     │ ◄───────────────────────── │  audit.jsonl     │               │  + CSF plug │
└──────────────┘                            └──────────────────┘               └─────────────┘

你可以询问什么

破坏性调用（delete、deny、restart、reissue、unblock 等）必须带有 confirm=true。模型必须获得明确的批准。

Related MCP server: cPanel MCP Server

要求

• Python 3.10+（推荐 3.12）或 Docker

• 具有 API 访问权限和登录密钥（而非主密码）的 DirectAdmin

• 对于 CSF 工具：ConfigServer Security & Firewall DirectAdmin 插件

• 从 MCP 主机到 https://your-panel:2222 的网络路径

快速开始（stdio — Claude Desktop / Cursor）

git clone https://github.com/OpenIaaS/directadmin-mcp-server.git
cd directadmin-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.sample .env
# edit .env — DA_URL, DA_USERNAME, DA_LOGIN_KEY

在管理员级别 → 账户管理器 → 登录密钥中生成登录密钥。将其限制为此机器的 IP。将密钥放入 .env：

DA_URL=https://panel.example.com:2222
DA_USERNAME=admin
DA_LOGIN_KEY=...
DA_SSL_VERIFY=true

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "directadmin": {
      "command": "/absolute/path/to/directadmin-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/directadmin-mcp/server.py"],
      "env": {
        "DA_URL": "https://panel.example.com:2222",
        "DA_USERNAME": "admin",
        "DA_LOGIN_KEY": "your-login-key"
      }
    }
  }
}

Cursor / 其他 MCP 客户端使用相同的 command + args + env 格式。

HTTP / SSE 模式（远程助手）

python -c "import secrets; print(secrets.token_urlsafe(48))"   # MCP_AUTH_TOKEN
# put the token in .env, keep MCP_HOST=127.0.0.1
python main.py

在前面放置带 TLS 的 Caddy 或 nginx。客户端向 /sse 发送 Authorization: Bearer <MCP_AUTH_TOKEN>。不要将令牌放在查询字符串中。

Docker（仅回环）：

cp .env.sample .env   # fill DA_* and MCP_AUTH_TOKEN
docker compose up -d --build
curl -sS http://127.0.0.1:8888/health

镜像以 UID 10001 运行，丢弃所有能力，并使用只读根文件系统。请参阅 SECURITY.md。

SSL 重新签发

管理员 SSL 图标（所有客户域名，Pro Pack，不在新版 API 中）：

ssl_admin_list
ssl_admin_reissue  domains=["shop.example.com","blog.example.com"]  confirm=true

这是 CMD_ADMIN_SSL action=multiple——与管理员级别 → 管理员 SSL 相同的操作。登录密钥必须被允许运行该命令。

单个域名（新版 API，DirectAdmin 1.660+ / 当前 Evolution）：

ssl_get_domain_acme_config  domain=shop.example.com  impersonate=alice
ssl_reissue_domain          domain=shop.example.com  impersonate=alice  confirm=true
ssl_reissue_domain          domain=shop.example.com  dry_run=true
ssl_reissue_server          confirm=true

ssl_reissue_domain 是 POST /api/domain-tls/{domain}/provision-certs。ssl_reissue_server 是 POST /api/server-tls/obtain。

在较旧的面板上，相同的意图是 ssl_reissue_domain_legacy（CMD_API_SSL Let's Encrypt 请求）。当您以管理员身份登录时，始终模拟所属用户——域名 TLS 是用户级资源。

相关：ssl_list_domain_certs、ssl_set_domain_acme_config、ssl_upload_cert_files、ssl_create_csr、ssl_install_self_signed、ssl_acme_dns_providers。

CSF / 防火墙解除阻止

CSF 不在新版 JSON API 中。这些工具向官方插件 /CMD_PLUGINS_ADMIN/csf/ 发送 POST。必须安装该插件。

一个 IP 通常会在两个地方被阻止（LFD 和 DirectAdmin BFM）。当客户被锁定时，请使用组合工具：

csf_search_ip                ip=203.0.113.44
bfm_ip_reason                ip=203.0.113.44
ip_block_reason              ip=203.0.113.44
firewall_unblock_everywhere  ip=203.0.113.44  confirm=true
csf_unblock_ip               ip=203.0.113.44  also_allow=true  confirm=true
bfm_unblock_ip               ip=203.0.113.44  confirm=true

csf_unblock_ip 运行插件快速解除阻止（action=kill → csf -dr + csf -tr + 丢弃状态）。also_allow=true 添加 1 小时的临时允许，以便下一次握手不会立即被重新封禁。

其他 CSF 工具：csf_allow_ip、csf_deny_ip、csf_ignore_ip、csf_flush_temp、csf_restart、csf_enable、csf_disable、csf_status。

csf_disable 默认被拒绝（TOOL_DENYLIST + ENABLE_CSF_DISABLE=false）。请改用 firewall_unblock_everywhere 解锁客户。

工具映射

精选工具按模块分组。其他所有内容可通过 da_api / da_legacy 访问。操作手册：docs/agent.md、docs/operations.md、docs/ssl.md、docs/csf.md、docs/propack.md、docs/cloudlinux.md、docs/hardening.md、docs/audit.md、docs/tokens.md。清单：docs/tools.json（273 个精选工具 + 320 个 swagger 操作）。

da_api 仅接受捆绑的 tools/api_spec.json 中存在的路径（从 https://demo.directadmin.com:2222/static/swagger.json 导出）。除非 ENABLE_EXECUTE=true，否则 /api/execute 被阻止。

配置

请参阅 .env.sample。重要旋钮：

安全

请阅读 SECURITY.md。简要版本：

• DirectAdmin 端的登录密钥 + IP 限制

• MCP 端的 Bearer 令牌 + 回环绑定 + TLS 代理

• 确认门、允许/拒绝工具列表、无通配符 CORS

• 密钥永远不会写入日志

• Docker：非 root、cap_drop: ALL、只读根

如果令牌或密钥泄露，请立即轮换两者。粘贴到聊天中的登录密钥已被烧毁。

开发

pip install -r requirements-dev.txt
pytest -q
ruff check .

添加精选工具：在 tools/ 中创建函数，使用 @mcp.tool() + @log_tool_call 装饰，验证输入（validate_ip、validate_domain、validate_username），如果调用会改变状态，则调用 guard_confirm。

当您用自己面板（/static/swagger.json）的新导出替换 tools/api_spec.json 时，通用目录会拾取新的 swagger 路径。

兼容性

已针对官方 New API swagger（info.version = 1.0，269 个路径 / 320 个操作）进行测试。旧版调用遵循 docs.directadmin.com/developer/api/legacy-api.html。

许可证

MIT。可自由使用、修改，并随您的面板工具一起发布。

本仓库是一个独立实现，由 OpenIaaS 于 2026年8月 首次发布。2025 年的 MIT 版本 （omryatia/directadmin-mcp） 提供了原始布局——入口点和模块名称。该起点作为衍生作品声明保留在 LICENSE 中。截至 2026年8月20日，它仅占代码树的一小部分：原始唯一代码行中约有二十分之一仍逐字出现；Python 源码 约为原来的三倍半，而领域工具（SSL、CSF、policy、audit）均为新增。

感谢 DirectAdmin 社区——文档、论坛，以及那些运行这些服务器 23 年以上 的运维人员。