DirectAdmin MCP Server

A production Model Context Protocol control plane for DirectAdmin. An AI agent (helpdesk, owner, or emergency sysadmin) talks to this process; the process talks to the panel. Every call is authenticated as a named hashed token, authorised by a profile (readonly / helpdesk / operator / break-glass), optionally confirmed, logged as structured JSON, rate-limited, and refused outside a maintenance window. SSL reissue and CSF/BFM unlock are first-class helpdesk actions — they are not the whole product.

The intended layout is an ops host, not an install on every DirectAdmin server. Bind a read-only listener for inspection and a separate write listener for approved changes (SSL reissue, CSF/BFM unlock). Per-server facts such as CloudLinux and the policy profile live in inventory.json on that host.

It covers the DirectAdmin New JSON API (320 operations from the official swagger) and the legacy CMD_API_* admin calls the New API still does not replace (create user, DNS, backups, BFM).

Read docs/agent.md and docs/tokens.md before pointing a model at production.

┌────────────┐  stdio / SSE  ┌─────────────────────────┐  HTTPS  ┌──────────────┐
│ Claude /   │ ────────────► │ directadmin-mcp-server  │ ──────► │ DirectAdmin  │
│ Cursor /   │               │ confirm · audit.jsonl   │   key   │ :2222 + CSF  │
│ any MCP    │ ◄──────────── │                         │         │              │
└────────────┘               └─────────────────────────┘         └──────────────┘

What you can ask

Write-shaped calls (delete, deny, restart, reissue, unblock, but also add, set, update, import, deploy, …) require confirm=true. The model must get an explicit go-ahead.

Requirements

• Python 3.10+ (3.12 recommended) or Docker

• DirectAdmin with API access and a login key (not the main password)

• For CSF tools: the ConfigServer Security & Firewall DirectAdmin plugin

• Network path from the MCP host to https://your-panel:2222

Quick start (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

Generate a login key in Admin Level → Account Manager → Login Keys. Restrict it to this machine's IP. Put the key in .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 / other MCP clients use the same command + args + env shape.

HTTP / SSE mode (remote assistant)

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

Put Caddy or nginx in front with TLS. Clients send Authorization: Bearer <MCP_AUTH_TOKEN> to /sse. Do not put the token in the query string.

Docker (loopback only):

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

The image runs as UID 10001, drops all capabilities, and uses a read-only root filesystem. See SECURITY.md.

SSL reissue

Admin SSL icon (all customer domains, Pro Pack, not in the New API):

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

This is CMD_ADMIN_SSL action=multiple — the same action as Admin Level → Admin SSL. The login key must be allowed to run that command.

One domain (New API, DirectAdmin 1.660+ / current 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 is POST /api/domain-tls/{domain}/provision-certs. ssl_reissue_server is POST /api/server-tls/obtain.

On older panels the same intent is ssl_reissue_domain_legacy (CMD_API_SSL Let's Encrypt request). Always impersonate the owning user when you are logged in as admin — domain TLS is a user-level resource.

Related: 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 / firewall unblock

CSF is not in the New JSON API. These tools POST to the official plugin /CMD_PLUGINS_ADMIN/csf/. The plugin must be installed.

An IP is often blocked in two places (LFD and DirectAdmin BFM). Use the combined tool when a customer is locked out:

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 runs the plugin Quick Unblock (action=kill → csf -dr + csf -tr + drop states). also_allow=true adds a 1-hour temporary allow so the next handshake is not immediately re-banned.

Other CSF tools: csf_allow_ip, csf_deny_ip, csf_ignore_ip, csf_flush_temp, csf_restart, csf_enable, csf_disable, csf_status.

csf_disable is denied by default (TOOL_DENYLIST + ENABLE_CSF_DISABLE=false). Unlock customers with firewall_unblock_everywhere instead.

Tool map

Curated tools are grouped by module. Everything else is reachable with da_api / da_legacy. Playbooks: 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. Inventory: docs/tools.json (303 curated tools + 320 swagger ops).

da_api only accepts paths that exist in the bundled tools/api_spec.json (exported from https://demo.directadmin.com:2222/static/swagger.json). /api/execute is blocked unless ENABLE_EXECUTE=true.

Configuration

See .env.sample. Important knobs:

Security

Read SECURITY.md. Short version:

• Login key + IP restriction on the DirectAdmin side

• Bearer token + loopback bind + TLS proxy on the MCP side

• Confirm gate, allow/deny tool lists, no wildcard CORS

• Secrets never written to logs

• Docker: non-root, cap_drop: ALL, read-only root

If a token or key leaks, rotate both immediately. A login key that was pasted into a chat is burned.

Development

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

Adding a curated tool: create a function in tools/, decorate with @mcp.tool() + @log_tool_call, and validate inputs (validate_ip, validate_domain, validate_username). @log_tool_call itself gates the call on confirm=true when needs_confirm() says so — no per-tool guard_confirm to remember.

The generic catalog picks up new swagger paths when you replace tools/api_spec.json with a fresh export from your own panel (/static/swagger.json).

Compatibility

Tested against the official New API swagger (info.version = 1.0, 269 paths / 320 operations). Legacy calls follow docs.directadmin.com/developer/api/legacy-api.html.

License

MIT. Use it, modify it, and ship it with your panel tooling.

This repository is an independent implementation, first published by OpenIaaS in August 2026. A 2025 MIT release (omryatia/directadmin-mcp) supplied the original layout — entrypoints and module names. That starting point is preserved as a derivative-work notice in LICENSE. As of 20 August 2026 it is a small fraction of the tree: about one in twenty of the original unique code lines still appear verbatim; the Python sources are roughly three and a half times larger, and the domain tools (SSL, CSF, policy, audit) are new.

With thanks to the DirectAdmin community — the documentation, the forum, and the operators who have been running these boxes for 23+ years.