GenieACS MCP

GenieACS-MCP

Uma pequena ponte que expõe qualquer instância do GenieACS como um servidor MCP v1 (JSON-RPC para LLMs) escrito em Go.

---

✨ O que você obtém

Tipo	Para que serve	URI MCP / id da ferramenta
Recursos	Consumir dados do GenieACS somente leitura	genieacs://device/{id} genieacs://file/{name} genieacs://tasks/{id} genieacs://devices/list genieacs://presets/list genieacs://provisions/list genieacs://faults/{id}
Ferramentas	Executar ações em um CPE através do 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

Tudo é exposto através de um único endpoint JSON-RPC (/mcp).
LLMs / Agentes podem: initialize → readResource → listTools → callTool … e assim por diante.

---

🚀 Início rápido (Docker Compose)

Siga as instruções de https://github.com/GeiserX/genieacs-container,; ele está incluído no arquivo docker compose de lá.

📦 Instalar via npm (transporte stdio)

npx genieacs-mcp

Ou instale globalmente:

npm install -g genieacs-mcp
genieacs-mcp

Isso baixa o binário Go pré-compilado para a sua plataforma e o executa com transporte stdio, compatível com qualquer cliente MCP.

🛠 Build 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

🔧 Configuração

Variável	Padrão	Descrição
ACS_URL	http://localhost:7557	Endpoint NBI do GenieACS (sem barra final)
ACS_USER	(vazio)	Nome de usuário de autenticação básica do GenieACS NBI
ACS_PASS	(vazio)	Senha de autenticação básica do GenieACS NBI
TRANSPORT	(vazio = HTTP)	Defina como stdio para transporte stdio
DEVICE_LIMIT	500	Máximo de dispositivos retornados por genieacs://devices/list
MCP_LISTEN_ADDR	127.0.0.1:8080	Endereço de escuta HTTP (usado apenas quando TRANSPORT não é stdio)
MCP_AUTH_TOKEN	(vazio)	Token Bearer para autenticação do transporte HTTP. Obrigatório quando MCP_LISTEN_ADDR não é loopback
MCP_ALLOWED_HOSTS	(vazio)	Valores extras de cabeçalho Host separados por vírgula para aceitar (ex.: um domínio de proxy reverso). Nomes loopback na porta de escuta são sempre permitidos
MCP_ALLOWED_ORIGINS	(vazio)	Valores extras de Origin do navegador separados por vírgula para aceitar (ex.: https://my-ai-app.com)

Segurança — transporte HTTP. O transporte HTTP valida os cabeçalhos Host e Origin em cada requisição para evitar DNS rebinding de uma página da web maliciosa alcançar um listener local. Requisições com um Host não confiável, ou um Origin presente mas não confiável, são rejeitadas com 403. O acesso loopback funciona sem configuração; se você expor o servidor através de um proxy reverso ou um hostname, adicione esse nome a MCP_ALLOWED_HOSTS (e MCP_ALLOWED_ORIGINS para clientes de navegador). O transporte stdio é não afetado e permanece o modo recomendado para clientes MCP locais.

Coloque-os em um arquivo .env (de .env.example) ou defina-os no ambiente.

Testes

Testado com Inspector e atualmente totalmente funcional. Antes de enviar um PR, certifique-se de que este servidor MCP se comporta bem por esse meio.

Falta testar com clientes MCP reais (LLMs clientes), então, por favor, envie seus PRs para melhorar as descrições caso ele não corresponda adequadamente aos serviços oferecidos por este servidor MCP.

Exemplo de configuração 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 – o melhor ACS de código aberto

MCP-GO – implementação MCP moderna

GoReleaser – releases multi-arquitetura sem dor

Mantenedores

@GeiserX.

Contribuindo

Sinta-se à vontade para mergulhar! Abra uma issue ou envie PRs.

GenieACS-MCP segue o Contributor Covenant Código de Conduta.

Ecossistema GenieACS

Este projeto faz parte de um conjunto mais amplo de ferramentas para trabalhar com GenieACS:

Projeto	Tipo	Descrição
genieacs-docker	Docker + Helm	Imagem Docker multi-arquitetura pronta para produção e Helm chart
genieacs-ansible	Coleção Ansible	Plugin de inventário dinâmico e módulos de gerenciamento de dispositivos
genieacs-ha	Integração HA	Integração com Home Assistant para monitoramento TR-069
n8n-nodes-genieacs	Nó n8n	Automação de fluxos de trabalho para GenieACS
genieacs-services	Defs de serviço	Definições de serviço Systemd/Supervisord
genieacs-sim-container	Simulador	Simulador GenieACS baseado em Docker para testes

Outros servidores MCP de GeiserX

• cashpilot-mcp — Monitoramento de renda passiva
• duplicacy-mcp — Monitoramento de saúde de backups
• lynxprompt-mcp — Modelos de configuração de IA
• pumperly-mcp — Preços de combustível e carregamento de veículos elétricos
• telegram-archive-mcp — Arquivo de mensagens do Telegram