Gerenciando Redes e Câmeras UniFi com Agentes LLM

Se você já configurou um firewall no UniFi Controller ou procurou um clipe específico de uma câmera no UniFi Protect, você sabe como é. Você abre a interface web, clica nos menus, procura a VLAN correta ou o endereço MAC do cliente. Automatizar essas tarefas com scripts é possível, mas a API da Ubiquiti tem suas peculiaridades e muda de versão para versão.

O projeto unifi-mcp adota uma abordagem diferente. É um conjunto de servidores usando o Model Context Protocol (MCP) que conecta assistentes de IA como Claude Code, Codex ou OpenClaw com controladores UniFi.

O que tem dentro do projeto

O repositório é estruturado como um monorepo Python e TypeScript. É dividido em três módulos principais cobrindo as áreas de produtos Ubiquiti:

1. Network — um módulo para gerenciar equipamentos de rede. Possui 186 ferramentas para trabalhar com VLANs, firewalls, clientes, redes Wi-Fi e dispositivos.
2. Protect — uma ferramenta de vigilância por vídeo. Inclui 61 funções para buscar eventos, analisar detecções de movimento e trabalhar com câmeras.
3. Access — gerenciamento de controle de acesso. Contém 36 funções para trabalhar com portas, credenciais e logs de acesso.

Além disso, o projeto inclui um servidor REST/GraphQL separado para clientes que ainda não suportam o protocolo MCP, e um sistema Cloud Relay para conectar uma rede local com agentes remotos via Cloudflare Workers.

Segurança e proteção contra erros fatais

Dar a um modelo de linguagem acesso direto ao firewall da sua rede doméstica ou do escritório é uma jogada ousada. Os desenvolvedores do unifi-mcp construíram dois mecanismos de segurança para reduzir o risco de quebrar algo.

O primeiro mecanismo é o conceito de visualizar e confirmar. Qualquer alteração de configuração primeiro retorna uma visualização: o agente de IA mostra o JSON exato ou a lista de regras que planeja enviar ao controlador e espera sua confirmação explícita.

O segundo elemento é a redação automática de dados sensíveis. Por padrão, todas as senhas Wi-Fi, chaves VPN, comunidades SNMP e tokens são removidas das respostas das ferramentas e substituídas por ***REDACTED***. O modelo não verá segredos no contexto e não poderá "vazar" acidentalmente em logs. No entanto, se você estiver executando um script de administração local confiável, você pode desativar o mascaramento via variáveis de ambiente.

Cenários práticos

Em vez de pesquisar manualmente na interface, você pode escrever consultas ao agente em linguagem simples.

Para o módulo de rede:

• "Mostrar todos os clientes na VLAN de convidados, sua intensidade de sinal e volume de tráfego"
• "Auditar regras de firewall, encontrar políticas duplicadas e conflitantes"
• "Criar uma regra que bloqueia o acesso à internet para dispositivos IoT de meia-noite às 6 da manhã"

Para sistemas de segurança:

• "Encontrar todos os eventos de reconhecimento de carro na entrada esta semana"
• "Cruzar timestamps: quem registrou ponto na porta da frente às 2 da manhã e qual câmera registrou movimento nas proximidades naquele momento"

A propósito, para tarefas frequentes o repositório já inclui habilidades integradas para agentes. Por exemplo, o Firewall Auditor executa 16 verificações de segurança de rede e gera uma pontuação em uma escala de 100 pontos com recomendações de remediação.

Como funciona tecnicamente

O projeto utiliza ativamente recursos de revisões recentes do protocolo MCP. Como uma ferramenta com 186 funções pode preencher a janela de contexto de um LLM antes mesmo da conversa começar, uma descoberta preguiçosa é implementada aqui. Inicialmente, o servidor passa apenas meta-ferramentas de busca para o assistente, e endpoints específicos são carregados sob demanda.

Iniciar servidores em um ambiente local é feito com um único comando via uvx:

uvx unifi-network-mcp@latest
uvx unifi-protect-mcp@latest
uvx unifi-access-mcp@latest

A configuração é passada através de variáveis de ambiente. Você precisará de uma conta de administrador local no controlador UniFi para conectar. Observação: contas com autenticação de dois fatores ou Ubiquiti SSO não funcionarão — você precisará criar um usuário de serviço local separado para o MCP funcionar.

Exemplo de configuração para Claude Desktop:

{
  "mcpServers": {
    "unifi-network": {
      "command": "uvx",
      "args": ["unifi-network-mcp@latest"],
      "env": {
        "UNIFI_HOST": "192.168.1.1",
        "UNIFI_USERNAME": "mcp-service-account",
        "UNIFI_PASSWORD": "your-safe-password"
      }
    }
  }
}

Vale a pena experimentar

O projeto parece maduro para sua classe: 588 estrelas no GitHub, commits ativos e suporte para Python 3.13+. Será útil para administradores de sistemas, entusiastas do Home Assistant e qualquer pessoa construindo automação em cima do Ubiquiti.

Se você tem um único ponto de acesso em casa, há pouco sentido em configurar um servidor MCP. Mas para infraestrutura complexa com firewalls, câmeras e controle de acesso, a capacidade de perguntar a um agente em vez de pesquisar manualmente nos painéis economiza muito tempo.