Servidor MCP de DirectAdmin

Un plano de control de Protocolo de Contexto de Modelos de producción para DirectAdmin. Un agente de IA (mesa de ayuda, propietario o administrador de emergencias) habla con este proceso; el proceso habla con el panel. Cada llamada se autentica con un token hash con nombre, se autoriza mediante un perfil (solo lectura / mesa de ayuda / operador / acceso total), opcionalmente se confirma, se registra como líneas JSON estructuradas, se limita por tasa y se rechaza fuera de una ventana de mantenimiento. La reemisión de SSL y el desbloqueo de CSF/BFM son acciones de primera clase de la mesa de ayuda; no son todo el producto.

El diseño previsto es un host de saltos junto al agente (no una instalación en cada servidor de DA): un listener de solo lectura para el agente conversador y un listener de escritura para las mutaciones permitidas. Los datos de la flota (CloudLinux, perfil) viven en inventory.json en ese host de saltos.

Cubre la API JSON nueva de DirectAdmin (320 operaciones del swagger oficial) y las llamadas CMD_API_* heredadas que la API nueva aún no reemplaza (crear usuario, copias de seguridad, BFM).

Lee docs/agent.md y docs/tokens.md antes de apuntar un modelo a producción.

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

Qué puedes pedir

Las llamadas destructivas (delete, deny, restart, reissue, unblock, …) requieren confirm=true. El modelo debe obtener una aprobación explícita.

Related MCP server: cPanel MCP Server

Requisitos

• Python 3.10+ (se recomienda 3.12) o Docker

• DirectAdmin con acceso a la API y una clave de acceso (no la contraseña principal)

• Para las herramientas de CSF: el plugin ConfigServer Security & Firewall de DirectAdmin

• Ruta de red desde el host MCP hasta https://tu-panel:2222

Inicio rápido (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

Genera una clave de acceso en Nivel de administrador → Administrador de claves de acceso. Restringe esa clave a la IP de esta máquina. Pon la clave en .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 y otros clientes MCP usan la misma forma de command + args + env.

Modo HTTP / SSE (asistente remoto)

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

Pon Caddy o nginx delante con TLS. Los clientes envían Authorization: Bearer <MCP_AUTH_TOKEN> a /sse. No pongas el token en la cadena de consulta.

Docker (solo loopback):

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

La imagen se ejecuta con UID 10001, sin capacidades y con el sistema de archivos raíz de solo lectura. Consulta SECURITY.md.

Reemisión de SSL

Icono de SSL de administrador (todos los dominios de clientes, Pro Pack, no está en la API nueva):

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

Esto es CMD_ADMIN_SSL action=multiple — la misma acción que en Nivel de administrador → SSL de administrador. A la clave de acceso se le debe permitir ejecutar ese comando.

Un dominio (API nueva, DirectAdmin 1.660+ / Evolution actual):

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 es POST /api/domain-tls/{domain}/provision-certs. ssl_reissue_server es POST /api/server-tls/obtain.

En paneles antiguos, la misma intención es ssl_reissue_domain_legacy (CMD_API_SSL con solicitud Let's Encrypt). Al iniciar sesión como administrador, haz siempre la suplantación del usuario propietario — el TLS de un dominio es un recurso de nivel de usuario.

Relacionadas: ssl_list_domain_certs, ssl_set_domain_acme_config, ssl_upload_cert_files, ssl_create_csr, ssl_install_self_signed, ssl_acme_dns_providers.

Desbloqueo de CSF / cortafuegos

CSF no está en la API JSON nueva. Estas herramientas hacen POST al plugin oficial /CMD_PLUGINS_ADMIN/csf/. El plugin debe estar instalado.

Una IP suele estar bloqueada en dos sitios (LFD y BFM de DirectAdmin). Usa la herramienta combinada cuando un cliente esté bloqueado:

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 ejecuta el plugin Quick Unblock (action=kill → csf -dr + csf -tr + estados de caída). also_allow=true añade una permisión temporal de 1 hora para que el siguiente apretón de manos no se vuelva a bloquear inmediatamente.

Otras herramientas de CSF: csf_allow_ip, csf_deny_ip, csf_ignore_ip, csf_flush_temp, csf_restart, csf_enable, csf_disable, csf_status.

csf_disable está denegada por defecto (TOOL_DENYLIST + ENABLE_CSF_DISABLE=false). Desbloquea a los clientes con firewall_unblock_everywhere en su lugar.

Mapa de herramientas

Las herramientas seleccionadas están agrupadas por módulo. Todo lo demás se alcanza con da_api / da_legacy. Guías: 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. Inventario: docs/tools.json (273 herramientas seleccionadas + 320 operaciones swagger).

da_api solo acepta rutas que existan en el tools/api_spec.json incluido (exportado desde https://demo.directadmin.com:2222/static/swagger.json). /api/execute está bloqueado a menos que ENABLE_EXECUTE=true.

Configuración

Consulta .env.sample. Valores importantes:

Seguridad

Lee SECURITY.md. Versión corta:

• Clave de acceso + restricción de IP en el lado de DirectAdmin

• Token Bearer + enlace a loopback + proxy TLS en el lado de MCP

• Puerta de confirmación, listas de herramientas de permitidos/denegados, sin CORS comodín

• Los secretos nunca se escriben en los registros

• Docker: sin root, cap_drop: ALL, raíz de solo lectura

Si un token o una clave se filtra, rota ambos inmediatamente. Una clave de acceso que se haya pegado en un chat está quemada.

Desarrollo

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

Para añadir una herramienta seleccionada: crea una función en tools/, decórala con @mcp.tool() + @log_tool_call, valida las entradas (validate_ip, validate_domain, validate_username) y llama a guard_confirm si la llamada muta el estado.

El catálogo genérico recoge las nuevas rutas swagger cuando reemplazas tools/api_spec.json con una exportación nueva de tu propio panel (/static/swagger.json).

Compatibilidad

Probado contra el swagger oficial de la New API (info.version = 1.0, 269 rutas / 320 operaciones). Las llamadas heredadas siguen docs.directadmin.com/developer/api/legacy-api.html.

Licencia

MIT. Úsalo, modifícalo y distribúyelo con tus herramientas de panel.

Este repositorio es una implementación independiente, publicada por primera vez por OpenIaaS en agosto de 2026. Una versión MIT de 2025 (omriyatia/directadmin-mcp) proporcionó el diseño original — puntos de entrada y nombres de módulos. Ese punto de partida se conserva como aviso de trabajo derivado en LICENSE. Al 20 de agosto de 2026 es una pequeña fracción del árbol: aproximadamente una de cada veinte líneas de código únicas originales siguen apareciendo textualmente; las fuentes de Python son aproximadamente tres veces y media más grandes, y las herramientas de dominio (SSL, CSF, policy, audit) son nuevas.

Con agradecimiento a la comunidad de DirectAdmin — la documentación, el foro y los operadores que han estado ejecutando estos servidores durante más de 23 años.