DirectAdmin MCP server
Commit Nov 1, 2026Provides an AI-driven control plane for DirectAdmin to manage users, SSL certificates, firewalls, and system services via the Model Context Protocol.
Also known as OpenIaaS/directadmin-mcp-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 1, 2026
- License
- MIT
What is DirectAdmin MCP?
DirectAdmin provides an AI-driven control plane for DirectAdmin to manage users, SSL certificates, firewalls, and system services via the Model Context Protocol.
Summary generated from the project's README
About DirectAdmin MCP server
Managing web hosting infrastructure through an AI agent is what this server enables for sysadmins and helpdesk teams. It acts as a control plane for DirectAdmin, allowing models like Claude or Cursor to perform administrative tasks via the Model Context Protocol. The server can be run locally using stdio or remotely via SSE, requiring a DirectAdmin URL, username, and a specific login key for authentication.
Users can manage a wide range of operations including SSL certificate reissues, firewall unblocking via CSF/BFM, and system service restarts. It supports both the modern DirectAdmin JSON API and legacy CMD_API calls for tasks like user creation or DNS management. To prevent accidental changes, the server includes a confirmation gate for destructive actions and supports different authorization profiles such as readonly, helpdesk, or operator. All actions are logged as structured JSON for auditing purposes.
What you can do with it
- 1Renew expired SSL certificatesAsk the AI to reissue a Let's Encrypt certificate for a specific domain.
- 2Resolve customer firewall lockoutsInstruct the agent to unblock a specific IP address from the CSF and BFM security layers.
- 3Monitor user resource consumptionRequest a list of all users who have exceeded their allocated storage or resource quotas.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
DA_LOGIN_KEYDA_SSL_VERIFYDA_URLDA_USERNAME
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableopeniaas/directadmin-mcp-server is public and reachablegithub.com/openiaas/directadmin-mcp-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/openiaas/directadmin-mcp-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubDirectAdmin 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
| You say | Tool |
|---|---|
| “Reissue the Let's Encrypt cert for shop.example.com” | ssl_reissue_domain |
| “The hostname cert expired, renew it” | ssl_reissue_server |
| “Customer 203.0.113.44 is locked out of CSF” | csf_unblock_ip / firewall_unblock_everywhere |
| “Is that IP blocked? Why? Tell the customer.” | ip_block_reason |
| “List users over quota” | users_list_all + users_get_usage |
| “Restart php-fpm74” | services_restart (needs ENABLE_SERVICE_CONTROL=true) |
Anything else in /api/* |
da_list_endpoints → da_api |
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).
| Module | Tools (prefix) | Notes |
|---|---|---|
| SSL | ssl_* |
Domain + hostname ACME, reissue, upload |
| CSF | csf_*, firewall_* |
Plugin; needs ENABLE_CSF=true |
| BFM | bfm_* |
Native panel blocks |
| Accounts | users_*, resellers_*, admins_* |
New API + CMD_API_ACCOUNT_* |
| Packages | packages_* |
User / reseller packages |
| System | system_*, license_*, maintenance_* |
Version, OS updates, usage |
| Services | services_* |
start/stop/restart/reload/logs |
| Settings | hostname_*, da_config_*, timezone_*, email_server_* |
directadmin.conf |
| Auth | login_keys_*, login_urls_*, mfa_*, sessions_* |
Prefer scoped keys |
| Security | modsecurity_*, clamav_*, security_txt_*, redis_* |
WAF / AV |
| Data | db_*, fm_*, email_*, dns_*, ips_*, backups_*, domains_*, ftp_*, cron_* |
Admin day-2 |
| Build | cb_*, plugins_*, wp_*, git_*, cpanel_* |
CustomBuild / apps |
| Pro Pack | unit_*, nginx_set_template, imapsync_*, propack_inventory |
Unit + templates; no web terminal |
| CloudLinux | cl_* |
Opt-in (ENABLE_CLOUDLINUX=false by default) |
| Policy | policy_status |
Live ENABLE_* flags; approval-token required? |
| Audit | audit_search, audit_recent, window_now |
Who did what, when, in-window? |
| Escape hatches | da_ping, da_list_endpoints, da_describe_endpoint, da_api, da_legacy |
Full swagger |
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:
| Variable | Default | Purpose |
|---|---|---|
DA_URL |
required | https://host:2222 |
DA_USERNAME / DA_LOGIN_KEY |
required | Login key, not the password |
DA_IMPERSONATE |
empty | Default login-as; prefer per-tool impersonate= |
DA_SSL_VERIFY |
true |
Verify the panel certificate |
MCP_HOST / PORT |
127.0.0.1 / 8888 |
HTTP bind |
MCP_AUTH_TOKEN |
empty | Required for HTTP in production |
MCP_ALLOWED_CIDRS |
empty | Optional client allow-list |
TOOL_ALLOWLIST / TOOL_DENYLIST |
empty / da_execute |
Reduce blast radius |
REQUIRE_CONFIRM |
true |
Destructive tools need confirm=true |
ENABLE_CSF |
true |
CSF plugin calls |
ENABLE_EXECUTE |
false |
/api/execute passthrough |
RATE_LIMIT_PER_MINUTE |
60 |
Per client identity |
AUDIT_LOG |
logs/audit.jsonl |
Redacted JSON lines |
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
| Transport | File | When |
|---|---|---|
| stdio | server.py |
Claude Desktop, Cursor, local agents |
| SSE | main.py → /sse |
Older remote MCP clients |
| HTTP health / tool list | main.py |
/health (liveness), /ready (panel), /mcp/tools |
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.
DirectAdmin MCP questions
What kind of actions can an AI agent perform with this server?
An AI agent can reissue SSL certificates, unblock IPs in CSF/BFM, list users over quota, restart services like php-fpm, and access various DirectAdmin API operations.