GenieACS MCP

GenieACS-MCP

Un pequeño puente que expone cualquier instancia de GenieACS como un servidor MCP v1 (JSON-RPC para LLMs) escrito en Go.

---

✨ Lo que obtienes

Tipo	Para qué	MCP URI / Tool id
Recursos	Consumir datos de GenieACS de solo lectura	genieacs://device/{id} genieacs://file/{name} genieacs://tasks/{id} genieacs://devices/list genieacs://presets/list genieacs://provisions/list genieacs://faults/{id}
Herramientas	Invocar acciones en un CPE a través de GenieACS	reboot_device download_firmware refresh_parameter set_parameter get_parameter manage_preset manage_provision search_devices tag_device connection_request delete_task retry_task

Todo se expone a través de un único endpoint JSON-RPC (/mcp).
Los LLMs / Agentes pueden: initialize → readResource → listTools → callTool … y así sucesivamente.

---

🚀 Inicio rápido (Docker Compose)

Sigue las instrucciones de https://github.com/GeiserX/genieacs-container,; está incluido en el archivo docker compose allí.

📦 Instalación vía npm (transporte stdio)

npx genieacs-mcp

O instalar globalmente:

npm install -g genieacs-mcp
genieacs-mcp

Esto descarga el binario Go precompilado para tu plataforma y lo ejecuta con transporte stdio, compatible con cualquier cliente MCP.

🛠 Compilación local

git clone https://github.com/GeiserX/genieacs-mcp
cd genieacs-mcp

# (optional) create .env from the sample
cp .env.example .env && $EDITOR .env

go run ./cmd/server

🔧 Configuración

Variable	Predeterminado	Descripción
ACS_URL	http://localhost:7557	Endpoint NBI de GenieACS (sin / final)
ACS_USER	(vacío)	Nombre de usuario de autenticación básica NBI de GenieACS
ACS_PASS	(vacío)	Contraseña de autenticación básica NBI de GenieACS
TRANSPORT	(vacío = HTTP)	Establecer a stdio para transporte stdio
DEVICE_LIMIT	500	Máximo de dispositivos devueltos por genieacs://devices/list
MCP_LISTEN_ADDR	127.0.0.1:8080	Dirección de escucha HTTP (solo se usa cuando TRANSPORT no es stdio)
MCP_AUTH_TOKEN	(vacío)	Token Bearer para autenticación de transporte HTTP. Requerido cuando MCP_LISTEN_ADDR no es de bucle local
MCP_ALLOWED_HOSTS	(vacío)	Valores de cabecera Host adicionales separados por comas para aceptar (p. ej., un dominio de proxy inverso). Los nombres de bucle local en el puerto de escucha siempre están permitidos
MCP_ALLOWED_ORIGINS	(vacío)	Valores de Origin de navegador adicionales separados por comas para aceptar (p. ej., https://my-ai-app.com)

Seguridad — Transporte HTTP. El transporte HTTP valida las cabeceras Host y Origin en cada solicitud para prevenir DNS rebinding desde una página web maliciosa que alcance un listener local. Las solicitudes con un Host no confiable, o un Origin presente pero no confiable, se rechazan con 403. El acceso de bucle local funciona sin configuración; si expones el servidor a través de un proxy inverso o un nombre de host, agrega ese nombre a MCP_ALLOWED_HOSTS (y MCP_ALLOWED_ORIGINS para clientes de navegador). El transporte stdio no se ve afectado y sigue siendo el modo recomendado para clientes MCP locales.

Colócalas en un archivo .env (de .env.example) o establécelas en el entorno.

Pruebas

Probado con Inspector y actualmente funciona completamente. Antes de hacer un PR, asegúrate de que este servidor MCP se comporte bien a través de este medio.

Falta probar con clientes MCP reales (LLMs clientes), así que por favor, envía tus PRs para mejorar las descripciones en caso de que no coincida adecuadamente con los servicios ofrecidos por este servidor MCP.

Ejemplo de configuración para LLMs clientes:

{
  "schema_version": "v1",
  "name_for_human": "GenieACS-MCP",
  "name_for_model": "genieacs_mcp",
  "description_for_human": "Full CPE management through GenieACS — parameter read/write, presets, provisions, firmware, tags, search, and task lifecycle.",
  "description_for_model": "Interact with a GenieACS TR-069 Auto-Configuration-Server (ACS) that manages CPE devices (routers, ONTs, gateways). First call initialize, then reuse the returned session id in header \"Mcp-Session-Id\" for every other call. Use readResource to fetch URIs that begin with genieacs:// (devices, presets, provisions, faults). Use listTools to discover available actions (parameter read/write, presets, provisions, tags, search, task management) and callTool to execute them.",
  "auth": { "type": "bearer", "token": "<MCP_AUTH_TOKEN value>" },
  "api": {
    "type": "jsonrpc-mcp",
    "url":  "http://localhost:8080/mcp",
    "init_method": "initialize",
    "session_header": "Mcp-Session-Id"
  },
  "logo_url": "https://raw.githubusercontent.com/GeiserX/genieacs-container/main/extra/logo.png",
  "contact_email": "acsdesk@protonmail.com",
  "legal_info_url": "https://github.com/GeiserX/genieacs-mcp/blob/main/LICENSE"
}

Créditos

GenieACS – el mejor ACS de código abierto

MCP-GO – implementación MCP moderna

GoReleaser – lanzamientos multi-arquitectura sin dolor

Mantenedores

@GeiserX.

Contribuciones

¡Siéntete libre de sumergirte! Abre un issue o envía PRs.

GenieACS-MCP sigue el Contributor Covenant Código de Conducta.

Ecosistema GenieACS

Este proyecto es parte de un conjunto más amplio de herramientas para trabajar con GenieACS:

Proyecto	Tipo	Descripción
genieacs-docker	Docker + Helm	Imagen Docker multi-arquitectura lista para producción y chart Helm
genieacs-ansible	Colección Ansible	Plugin de inventario dinámico y módulos de gestión de dispositivos
genieacs-ha	Integración HA	Integración de Home Assistant para monitoreo TR-069
n8n-nodes-genieacs	Nodo n8n	Automatización de flujos de trabajo para GenieACS
genieacs-services	Definiciones de Servicio	Definiciones de servicios Systemd/Supervisord
genieacs-sim-container	Simulador	Simulador GenieACS basado en Docker para pruebas

Otros Servidores MCP de GeiserX

• cashpilot-mcp — Monitoreo de ingresos pasivos
• duplicacy-mcp — Monitoreo de salud de respaldos
• lynxprompt-mcp — Planos de configuración de IA
• pumperly-mcp — Precios de combustible y carga de vehículos eléctricos
• telegram-archive-mcp — Archivo de mensajes de Telegram