OPNsense MCP Server

Servidor MCP seguro para gerenciar firewalls OPNsense - 62 ferramentas para firewall, DNS, DHCP, VPN, HAProxy e auditoria de segurança com modo somente leitura padrão e proteção automática de reversão.

GitHub

Documentação

Servidor MCP OPNsense

Um servidor Model Context Protocol (MCP) seguro para gerenciar firewalls OPNsense por meio de assistentes de IA como Claude Code, Cursor e outras ferramentas compatíveis com MCP.

81 ferramentas em 10 domínios: sistema, firewall, rede, DNS, DHCP, VPN, HAProxy, serviços, diagnósticos e segurança.

Requisitos

Python 3.11+
OPNsense 24.7 ou mais recente — o servidor MCP depende dos endpoints de API baseados em MVC introduzidos no OPNsense 24.7. Versões mais antigas usam uma estrutura de API diferente que não é compatível. O servidor detecta automaticamente a versão do OPNsense na primeira conexão e seleciona a nomenclatura correta de endpoint (camelCase para versões anteriores à 25.7, snake_case para 25.7+). OPNsense 26.x é totalmente suportado, incluindo seu formato alterado de resposta de status de firmware.

Modelo de Segurança

Este servidor MCP foi projetado com a segurança como preocupação principal:

Somente leitura por padrão — operações de escrita exigem aceitação explícita via OPNSENSE_ALLOW_WRITES=true
Savepoint/rollback (somente OPNsense < 26.7) — onde o OPNsense ainda oferece a API de savepoint, as modificações no firewall usam sua reversão automática integrada de 60 segundos; as alterações devem ser explicitamente confirmadas ou serão revertidas automaticamente. O OPNsense 26.7 removeu essa API upstream — o servidor detecta o endpoint ausente em tempo de execução e aplica as alterações no firewall imediatamente, sem reversão automática
Lista de bloqueio de endpoints — endpoints perigosos (halt, reboot, poweroff, firmware update/upgrade) são bloqueados permanentemente no nível do cliente de API e nunca podem ser chamados
Somente API — sem acesso SSH, sem execução de comandos, sem manipulação direta de arquivos de configuração
Transporte local — somente STDIO, sem endpoints HTTP/SSE expostos à rede
Sem exposição de credenciais — chaves de API nunca são incluídas na saída das ferramentas, logs ou mensagens de erro
Validação de entrada — parâmetros de hostname são validados contra injeção de metacaracteres de shell
Remoção de dados sensíveis — o backup de configuração remove senhas e chaves por padrão

Início Rápido

1. Criar uma Chave de API OPNsense

Faça login na interface web do seu OPNsense
Vá para System > Access > Users
Edite um usuário existente ou crie um usuário de API dedicado:
- Para uso em produção, crie um usuário dedicado (ex.: mcp-api) com apenas os privilégios necessários
- Para acesso somente leitura, atribua o usuário a um grupo com acesso de API somente leitura
Role até a seção API keys e clique no botão +
Um par chave/segredo será gerado e um arquivo (apikey.txt) será baixado
O arquivo contém duas linhas — key=your-api-key-here e secret=your-api-secret-here
Armazene essas credenciais com segurança — o segredo não pode ser recuperado novamente do OPNsense

Dica: Para uma configuração somente leitura (recomendada para começar), você não precisa alterar nenhuma permissão — o acesso padrão da API é suficiente para todas as ferramentas somente leitura.

2. Instalar

# Using pip
pip install opnsense-mcp-server

# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server

# Using Docker
docker pull uhlenheide/opnsense-mcp-server

# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .

Imagem Docker: a imagem oficial é uhlenheide/opnsense-mcp-server, publicada a partir deste repositório por .github/workflows/publish-docker.yml em cada tag v*. Não existe imagem lucamarien/opnsense-mcp-server — versões anteriores do README a nomearam por engano.

3. Configurar Seu Assistente de IA

Claude Code

Adicione ao .mcp.json do seu projeto:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false",
        "OPNSENSE_ALLOW_WRITES": "false"
      }
    }
  }
}

Alternativa: Use "command": "python", "args": ["-m", "opnsense_mcp"] se o CLI opnsense-mcp não estiver no seu PATH.

Ou adicione globalmente ao ~/.claude/claude_code_config.json.

Claude Code (Docker)

{
  "mcpServers": {
    "opnsense": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPNSENSE_URL=https://192.168.1.1/api",
        "-e", "OPNSENSE_API_KEY=your-api-key-here",
        "-e", "OPNSENSE_API_SECRET=your-api-secret-here",
        "-e", "OPNSENSE_VERIFY_SSL=false",
        "-e", "OPNSENSE_ALLOW_WRITES=false",
        "uhlenheide/opnsense-mcp-server"
      ]
    }
  }
}

Cursor

Adicione às configurações de MCP do seu Cursor (Settings > MCP):

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Configuração

Variável de Ambiente	Padrão	Descrição
`OPNSENSE_URL`	(obrigatório)	URL base da API OPNsense (deve terminar com `/api`)
`OPNSENSE_API_KEY`	(obrigatório)	Chave de API das configurações do usuário OPNsense
`OPNSENSE_API_SECRET`	(obrigatório)	Segredo de API das configurações do usuário OPNsense
`OPNSENSE_VERIFY_SSL`	`true`	Verificar certificado SSL (`false` para certificados autoassinados)
`OPNSENSE_ALLOW_WRITES`	`false`	Habilitar operações de escrita (regras de firewall, controle de serviços)

Portas personalizadas: Se a interface web do seu OPNsense estiver em uma porta não padrão (ex.: 10443), inclua-a na URL: https://192.168.1.1:10443/api

Ferramentas Disponíveis (81)

Sistema (7 ferramentas)

Ferramenta	Descrição
`opn_system_status`	Informações do sistema, incluindo versão do firmware, nome do produto e arquitetura
`opn_list_services`	Listar todos os serviços e seu status de execução. Parâmetros: `search`, `limit`
`opn_gateway_status`	Disponibilidade de gateway, latência e verificações de saúde dpinger
`opn_download_config`	Baixar backup `config.xml` com remoção opcional de dados sensíveis. Parâmetros: `include_sensitive` (padrão: `false` — senhas e chaves são ocultadas)
`opn_scan_config`	Escanear a configuração completa, analisá-la em seções e coletar inventário em tempo de execução (firmware, plugins, DHCP, DNS, interfaces, serviços). Os resultados são armazenados em cache por sessão. Parâmetros: `force`
`opn_get_config_section`	Obter uma seção específica da configuração como JSON estruturado. Parâmetros: `section`, `include_sensitive`
`opn_mcp_info`	Versão do servidor MCP, status do modo de escrita, versão detectada do OPNsense, estilo da API e se as escritas no firewall ainda têm proteção de savepoint/rollback

Rede (5 ferramentas)

Ferramenta	Descrição
`opn_interface_stats`	Estatísticas de tráfego por interface (bytes de entrada/saída, pacotes, erros)
`opn_arp_table`	Tabela ARP mostrando mapeamentos de IP para endereço MAC
`opn_ndp_table`	Tabela NDP (Neighbor Discovery Protocol) mostrando mapeamentos de IPv6 para endereço MAC
`opn_ipv6_status`	Configuração IPv6 e status de endereço para todas as interfaces (método, endereços ativos, resumo)
`opn_list_static_routes`	Rotas estáticas configuradas. Parâmetros: `search`, `limit`

Firewall (21 ferramentas)

Ferramenta	Descrição	Escritas
`opn_list_firewall_rules`	Listar regras de filtro de firewall MVC. Parâmetros: `search`, `limit`	Não
`opn_list_firewall_aliases`	Listar definições de alias (listas de IP, grupos de portas, GeoIP, URLs). Parâmetros: `search`, `limit`	Não
`opn_list_nat_rules`	Listar regras de encaminhamento de porta NAT (DNAT). Parâmetros: `search`, `limit`	Não
`opn_list_firewall_categories`	Listar categorias de regras de firewall e seus UUIDs. Parâmetros: `search`, `limit`	Não
`opn_firewall_log`	Entradas recentes do log do firewall com filtragem no lado do cliente. Parâmetros: `source_ip`, `destination_ip`, `action`, `interface`, `limit`	Não
`opn_confirm_changes`	Confirmar alterações pendentes, cancelando a reversão automática de 60 segundos (OPNsense < 26.7; uma operação sem efeito retornando `not_applicable` em 26.7+). Parâmetros: `revision`	Sim
`opn_toggle_firewall_rule`	Alternar o estado habilitado/desabilitado de uma regra com savepoint (OPNsense < 26.7). Parâmetros: `uuid`	Sim
`opn_add_firewall_rule`	Criar uma nova regra de filtro com savepoint (OPNsense < 26.7). Parâmetros: `action`, `direction`, `interface`, `ip_protocol`, `protocol`, `source_net`, `destination_net`, `destination_port`, `description`	Sim
`opn_delete_firewall_rule`	Excluir uma regra de filtro por UUID com savepoint (OPNsense < 26.7). Parâmetros: `uuid`	Sim
`opn_add_alias`	Criar um novo alias. Parâmetros: `name`, `alias_type`, `content`, `description`	Sim
`opn_add_nat_rule`	Criar uma regra de encaminhamento de porta NAT com savepoint (OPNsense < 26.7). Parâmetros: `destination_port`, `target_ip`, `interface`, `protocol`, `target_port`, `description`	Sim
`opn_add_firewall_category`	Criar uma nova categoria de regra de firewall. Parâmetros: `name`, `color`	Sim
`opn_delete_firewall_category`	Excluir uma categoria de regra de firewall por UUID com savepoint (OPNsense < 26.7). Parâmetros: `uuid`	Sim
`opn_set_rule_categories`	Atribuir categorias a uma regra de firewall com savepoint (OPNsense < 26.7). Parâmetros: `uuid`, `categories`	Sim
`opn_add_icmpv6_rules`	Criar regras ICMPv6 essenciais necessárias para a operação IPv6 (NDP, RA, ping6) conforme RFC 4890. Parâmetros: `interface`	Sim
`opn_update_alias`	Atualizar um alias existente (nome, conteúdo, tipo, descrição). Leitura-modificação-escrita. Parâmetros: `uuid`, `name`, `content`, `description`, `alias_type`, `enabled`	Sim
`opn_delete_alias`	Excluir um alias por UUID. Verificar referências de regras primeiro. Parâmetros: `uuid`	Sim
`opn_toggle_alias`	Alternar o estado habilitado/desabilitado do alias. Parâmetros: `uuid`	Sim
`opn_update_firewall_rule`	Atualizar campos de regra de filtro com savepoint (OPNsense < 26.7). Parâmetros: `uuid`, `action`, `direction`, `interface`, `ip_protocol`, `protocol`, `source_net`, `source_not`, `source_port`, `destination_net`, `destination_not`, `destination_port`, `gateway`, `log`, `quick`, `sequence`, `categories`, `description`, `enabled`	Sim
`opn_update_nat_rule`	Atualizar regra de encaminhamento de porta NAT com savepoint (OPNsense < 26.7). Parâmetros: `uuid`, `interface`, `protocol`, `destination_port`, `target_ip`, `target_port`, `description`, `enabled`	Sim
`opn_delete_nat_rule`	Excluir uma regra de encaminhamento de porta NAT por UUID com savepoint (OPNsense < 26.7). Parâmetros: `uuid`	Sim

Nota: A proteção de savepoint só existe no OPNsense < 26.7. Em 26.7+, essas ferramentas aplicam alterações imediatamente e permanentemente — consulte Operações de Escrita e Savepoints.

DNS (13 ferramentas)

Ferramenta	Descrição	Escritas
`opn_list_dns_overrides`	Overrides de host Unbound (registros DNS locais). Parâmetros: `search`, `limit`	Não
`opn_list_dns_forwards`	Zonas de encaminhamento DNS (servidores específicos de domínio). Parâmetros: `search`, `limit`	Não
`opn_dns_stats`	Estatísticas do resolvedor Unbound (consultas, acertos de cache, tempo de atividade)	Não
`opn_reconfigure_unbound`	Aplicar alterações pendentes na configuração do resolvedor DNS	Sim
`opn_add_dns_override`	Adicionar um override de host DNS Unbound (registro A/AAAA) e aplicar imediatamente. Parâmetros: `hostname`, `domain`, `server`, `description`	Sim
`opn_list_dnsbl`	Listar configurações de listas de bloqueio DNSBL com provedores e status. Parâmetros: `search`, `limit`	Não
`opn_get_dnsbl`	Obter configuração completa de DNSBL por UUID (provedores, listas de permissão, configurações). Parâmetros: `uuid`	Não
`opn_set_dnsbl`	Atualizar configurações de DNSBL (leitura-modificação-escrita). Parâmetros: `uuid`, `enabled`, `providers`, `allowlists`, `blocklists`, `wildcards`, etc.	Sim
`opn_add_dnsbl_allowlist`	Adicionar domínios à lista de permissão DNSBL sem sobrescrever. Parâmetros: `uuid`, `domains`	Sim
`opn_remove_dnsbl_allowlist`	Remover domínios da lista de permissão DNSBL. Parâmetros: `uuid`, `domains`	Sim
`opn_update_dnsbl`	Recarregar arquivos de lista de bloqueio DNSBL e reiniciar o Unbound (sem alteração de configuração, ferramenta de recuperação)	Sim
`opn_update_dns_override`	Atualizar um override de host DNS Unbound e aplicar imediatamente. Parâmetros: `uuid`, `hostname`, `domain`, `server`, `description`, `enabled`	Sim
`opn_delete_dns_override`	Excluir um override de host DNS Unbound e aplicar imediatamente. Parâmetros: `uuid`	Sim

DHCP (8 ferramentas)

Ferramenta	Descrição	Grava
`opn_list_dhcp_leases`	Concessões DHCPv4 ativas do servidor ISC DHCP	Não
`opn_list_kea_leases`	Concessões DHCPv4 do servidor Kea DHCP. Parâmetros: `search`, `limit`	Não
`opn_list_dnsmasq_leases`	Concessões DHCPv4 e DHCPv6 do servidor DNS/DHCP dnsmasq. Parâmetros: `search`, `limit`	Não
`opn_list_dnsmasq_ranges`	Faixas de endereços DHCP configuradas (tanto DHCPv4 quanto DHCPv6 com configuração RA). Parâmetros: `search`, `limit`	Não
`opn_add_dnsmasq_range`	Criar uma nova faixa DHCP (IPv4 ou IPv6 com configuração de Router Advertisement). Parâmetros: `interface`, `start_addr`, `end_addr`, `prefix_len`, `ra_mode`, `lease_time`, `description`	Sim
`opn_reconfigure_dnsmasq`	Aplicar alterações pendentes de configuração DNS/DHCP do dnsmasq	Sim
`opn_update_dnsmasq_range`	Atualizar uma faixa DHCP (endereços, tempo de concessão, configuração RA) e aplicar. Parâmetros: `uuid`, `interface`, `start_addr`, `end_addr`, `prefix_len`, `ra_mode`, `lease_time`, `description`, `enabled`	Sim
`opn_delete_dnsmasq_range`	Excluir uma faixa DHCP por UUID e aplicar. Parâmetros: `uuid`	Sim

VPN (3 ferramentas)

Ferramenta	Descrição
`opn_wireguard_status`	Status do túnel WireGuard e pares (requer plugin os-wireguard)
`opn_ipsec_status`	Status do túnel VPN IPsec — sessões IKE (Fase 1) e ESP/AH (Fase 2)
`opn_openvpn_status`	Status da conexão OpenVPN — instâncias, sessões e rotas

HAProxy (8 ferramentas)

Gerenciamento completo de configuração para o balanceador de carga HAProxy (requer plugin os-haproxy).

Ferramenta	Descrição	Grava
`opn_haproxy_status`	Status do serviço HAProxy e saúde dos backends	Não
`opn_haproxy_search`	Pesquisar recursos HAProxy por tipo. Parâmetros: `resource_type` (frontends/backends/servers/actions/acls/healthchecks/errorfiles/resolvers/mailers), `search`, `limit`	Não
`opn_haproxy_get`	Obter configuração detalhada de um recurso específico. Parâmetros: `resource_type`, `uuid`	Não
`opn_haproxy_configtest`	Validar a sintaxe da configuração do HAProxy antes de aplicar	Não
`opn_haproxy_add`	Criar um novo recurso HAProxy. Parâmetros: `resource_type`, `config` (dicionário de valores de campo)	Sim
`opn_haproxy_update`	Atualizar um recurso HAProxy existente (atualizações parciais). Parâmetros: `resource_type`, `uuid`, `config`	Sim
`opn_haproxy_delete`	Excluir um recurso HAProxy por UUID. Parâmetros: `resource_type`, `uuid`	Sim
`opn_reconfigure_haproxy`	Aplicar alterações pendentes de configuração do HAProxy	Sim

Nota: Alterações no HAProxy NÃO usam proteção de savepoint — elas são aplicadas imediatamente na reconfiguração. Sempre chame opn_haproxy_configtest antes de opn_reconfigure_haproxy.

Serviços (11 ferramentas)

Ferramenta	Descrição	Grava
`opn_list_acme_certs`	Certificados ACME/Let's Encrypt e seu status. Parâmetros: `search`, `limit`	Não
`opn_list_cron_jobs`	Trabalhos cron agendados. Parâmetros: `search`, `limit`	Não
`opn_crowdsec_status`	Status do mecanismo de segurança CrowdSec e decisões ativas	Não
`opn_crowdsec_alerts`	Alertas de segurança CrowdSec (ameaças detectadas). Parâmetros: `search`, `limit`	Não
`opn_list_ddns_accounts`	Contas Dynamic DNS e seu status de atualização. Parâmetros: `search`, `limit`	Não
`opn_add_ddns_account`	Criar uma nova conta Dynamic DNS. Parâmetros: `service`, `hostname`, `username`, `password`, `checkip`, `interface`, `description`	Sim
`opn_reconfigure_ddclient`	Aplicar alterações pendentes de configuração do Dynamic DNS	Sim
`opn_update_ddns_account`	Atualizar uma conta Dynamic DNS (senha é somente gravação). Parâmetros: `uuid`, `service`, `hostname`, `username`, `password`, `checkip`, `interface`, `description`, `enabled`	Sim
`opn_delete_ddns_account`	Excluir uma conta Dynamic DNS por UUID. Parâmetros: `uuid`	Sim
`opn_mdns_repeater_status`	Status e configuração do mDNS Repeater (habilitado, interfaces, lista de bloqueio). Requer plugin `os-mdns-repeater`	Não
`opn_configure_mdns_repeater`	Configurar mDNS Repeater para descoberta de dispositivos entre VLANs (HomeKit, Chromecast, AirPlay). Parâmetros: `enabled`, `interfaces`	Sim

Diagnóstico (4 ferramentas)

Ferramenta	Descrição
`opn_ping`	Enviar ping a um host a partir do firewall para testar conectividade. Parâmetros: `host`, `count` (1-10, padrão 3)
`opn_traceroute`	Traçar caminho de rede até um destino. Parâmetros: `host`, `protocol` (ICMP/UDP/TCP), `ip_version` (4/6)
`opn_dns_lookup`	Consulta DNS a partir do firewall. Parâmetros: `hostname`, `server` (servidor DNS personalizado opcional)
`opn_pf_states`	Consultar tabela de estados PF ativa. Parâmetros: `search`, `limit` (máx. 1000)

Segurança (1 ferramenta)

Ferramenta Descrição

opn_security_audit Auditoria de segurança abrangente em 11 áreas: firmware, regras de firewall (MVC + legado, agrupamento de portas, protocolos inseguros), encaminhamento NAT, segurança DNS (DNSSEC, DoT), endurecimento do sistema (SSH, HTTPS, syslog), serviços, certificados (ACME + sistema + CAs), VPN (configuração WireGuard, IPsec, OpenVPN), HAProxy (cabeçalhos, health checks), gateways. Descobertas marcadas com referências de conformidade PCI DSS v4.0, BSI IT-Grundschutz, NIST 800-41, CIS.

Ferramenta	Descrição
`opn_security_audit`	Auditoria de segurança abrangente em 11 áreas: firmware, regras de firewall (MVC + legado, agrupamento de portas, protocolos inseguros), encaminhamento NAT, segurança DNS (DNSSEC, DoT), endurecimento do sistema (SSH, HTTPS, syslog), serviços, certificados (ACME + sistema + CAs), VPN (configuração WireGuard, IPsec, OpenVPN), HAProxy (cabeçalhos, health checks), gateways. Descobertas marcadas com referências de conformidade PCI DSS v4.0, BSI IT-Grundschutz, NIST 800-41, CIS.

Operações de Gravação e Savepoints

Operações de gravação exigem OPNSENSE_ALLOW_WRITES=true. Em OPNsense < 26.7, alterações no firewall adicionalmente passam pelo mecanismo de savepoint do OPNsense:

Antes de qualquer alteração no firewall, um savepoint é criado automaticamente
A alteração é aplicada (alternar regra, adicionar ou excluir)
Uma contagem regressiva de 60 segundos começa — se não for confirmada, o OPNsense reverte automaticamente a alteração
Use opn_confirm_changes com o revision retornado para tornar as alterações permanentes

Nessas versões, se um assistente de IA fizer uma alteração ruim no firewall que o bloqueie, a alteração será revertida automaticamente em 60 segundos.

OPNsense 26.7 removeu a API de savepoint/rollback upstream, portanto não há reversão automática em 26.7+. O servidor não define um corte de versão fixo: ele testa o endpoint de savepoint na primeira gravação no firewall e, se o OPNsense responder que o endpoint não existe, degrada para aplicação direta pelo restante da sessão. Verifique opn_mcp_info — seu campo savepoint_support relata true, false ou null se nenhuma gravação foi testada ainda. As ferramentas de gravação então retornam um revision vazio, opn_confirm_changes responde com status: "not_applicable", e cada alteração no firewall é imediata e permanente.

Aviso: Em OPNsense 26.7+, faça um backup da configuração (opn_download_config, ou System > Configuration > Backups) antes de habilitar gravações, e mantenha acesso fora de banda à máquina — uma regra que o bloqueie não será revertida sozinha.

Nota: opn_reconfigure_unbound, opn_reconfigure_haproxy, opn_reconfigure_ddclient, opn_reconfigure_dnsmasq e opn_configure_mdns_repeater exigem gravações, mas não usam savepoints — elas aplicam alterações de configuração de serviço e não são revertíveis automaticamente.

Suporte a IPv6

Totalmente Automatizado via MCP

Regras de Firewall IPv6 — Criar regras com ip_protocol="inet6" (protegido por savepoint em OPNsense < 26.7)
Bindings IPv6 no HAProxy — Frontends com endereços de bind [::]:443 ou [2001:db8::1]:443
Backends IPv6 no HAProxy — Servidores com endereços IPv6, resolvePrefer: ipv6 em backends
Dynamic DNS com IPv6 — Contas DDNS com métodos checkip compatíveis com IPv6
Faixas DHCPv6 (dnsmasq) — Faixas DHCP IPv6 com configuração de Router Advertisement
Registros DNS AAAA — Overrides de host no Unbound com endereços IPv6
Diagnóstico IPv6 — Traceroute com ip_version="6", ping via hostname

Requer Configuração Manual na GUI

Essas configurações não têm suporte à API MVC no OPNsense e devem ser configuradas via GUI web:

Configuração IPv6 na WAN — PPPoE com delegação de prefixo DHCPv6, IPv6 estático, SLAAC
Endereçamento IPv6 na LAN — Modo Track Interface, atribuição estática /64, ID de prefixo
Atribuição de interfaces — Atribuir portas físicas aos papéis WAN/LAN/OPT
Túneis 6to4/6rd — Mecanismos de túnel de transição

Limitações Conhecidas

ISC DHCP / Kea DHCPv6: Não implementado. Apenas dnsmasq (o padrão moderno) é suportado para faixas DHCPv6 e Router Advertisements. ISC DHCP está obsoleto; a visibilidade de concessões DHCPv6 do Kea é limitada na API.
radvd: Não implementado como um conjunto de ferramentas separado. O Dnsmasq lida com Router Advertisements nativamente via configuração de faixa. Apenas um daemon RA deve ser executado por interface.
Regras de firewall dual-stack: inet46 (dual-stack) funciona corretamente em regras da API MVC (opn_add_firewall_rule). No entanto, inet46 em regras de filtro XML legadas (GUI) silenciosamente não produz saída PF — este é um bug conhecido do OPNsense que afeta apenas regras legadas.
Regras legadas da GUI: Regras de firewall criadas via GUI tradicional do OPNsense não são acessíveis através da API MVC. Use opn_get_config_section("filter") para acesso somente leitura.

Fluxo de Trabalho Recomendado para Migração IPv6

Manual (GUI): Configurar IPv6 na WAN (DHCPv6-PD do ISP ou estático)
Manual (GUI): Configurar interfaces LAN (modo Track Interface para delegação de prefixo)
MCP: Configurar Router Advertisements via opn_add_dnsmasq_range com flags RA
MCP: Criar regras de firewall IPv6 (ICMPv6 deve ser permitido para NDP/RA/PMTUD)
MCP: Adicionar registros DNS IPv6 via opn_add_dns_override
MCP: Configurar Dynamic DNS com método checkip IPv6
MCP: Adicionar endereços de bind IPv6 aos frontends do HAProxy
MCP: Verificar com opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status

Compatibilidade de Versões

Versão do OPNsense	Status
24.7 (Thriving Tiger)	Suportada
25.1 (Ultimate Unicorn)	Suportada
25.7 (Visionary Viper)	Suportada (detecta automaticamente API snake_case)
26.1+	Suportada

O servidor detecta automaticamente a versão do OPNsense na primeira conexão e seleciona a convenção de nomenclatura correta do endpoint da API (camelCase para pré-25.7, snake_case para 25.7+).

Nota sobre regras de firewall: opn_list_firewall_rules mostra regras gerenciadas via API MVC/automação. Regras configuradas através da GUI do OPNsense usam um formato legado não acessível via esta API. Esta é uma limitação conhecida do OPNsense.

Solução de Problemas

Problemas de Conexão

Erros de "Connection refused" ou timeout

Verifique se OPNSENSE_URL termina com /api (ex.: https://192.168.1.1/api)
Se estiver usando uma porta não padrão, inclua-a: https://192.168.1.1:10443/api
Garanta que a GUI web do OPNsense esteja acessível a partir da máquina que executa o servidor MCP

Erros de certificado SSL

Para certificados autoassinados (configuração padrão do OPNsense), defina OPNSENSE_VERIFY_SSL=false
Para produção, instale um certificado adequado no OPNsense e mantenha OPNSENSE_VERIFY_SSL=true

Problemas de Autenticação

401 Não Autorizado

Verifique se OPNSENSE_API_KEY e OPNSENSE_API_SECRET estão corretos
Chaves de API diferenciam maiúsculas de minúsculas — copie-as exatamente do apikey.txt baixado
Verifique se o usuário da API não está desabilitado no OPNsense
Verifique se o usuário da API tem privilégios suficientes para as operações que você está tentando

403 Proibido

O usuário da API pode não ter permissões para o endpoint solicitado
Para operações de gravação, garanta que OPNSENSE_ALLOW_WRITES=true esteja definido

Problemas Específicos de Ferramentas

`opn_list_firewall_rules` retorna resultados vazios

Esta ferramenta mostra apenas regras MVC/automação, não regras legadas da GUI
Crie regras via API de automação ou opn_add_firewall_rule para vê-las

`opn_ping` expira

O firewall pode não ter rota para o host de destino
Verifique o status do gateway com opn_gateway_status
O timeout padrão é de 30 segundos (30 ciclos de polling)

`opn_download_config` mostra valores `[REDACTED]`

Este é o comportamento padrão para segurança. Passe include_sensitive=true para incluir senhas e chaves (use com cautela em conversas de IA)

Operações de escrita falham com "writes not enabled"

Defina OPNSENSE_ALLOW_WRITES=true na configuração do seu servidor MCP
Isso está intencionalmente desabilitado por padrão por segurança

A confirmação de savepoint falha

O parâmetro revision deve corresponder exatamente ao que foi retornado pela operação de escrita
As confirmações devem ocorrer dentro de 60 segundos ou a alteração é revertida automaticamente
No OPNsense 26.7+ não há API de savepoint: as ferramentas de escrita retornam um revision vazio e opn_confirm_changes retorna status: "not_applicable". Isso é esperado, não uma falha — a alteração já foi aplicada permanentemente

Comandos de Diagnóstico

Se você precisar depurar o servidor MCP:

# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status

# Run the server directly
python -m opnsense_mcp

# Run tests to verify installation
pytest -v

Desenvolvimento

# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"

# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v

# Full CI pipeline (lint, format, type check, security scan, tests)
make validate

# Individual checks
ruff check src/ tests/          # Lint (includes bandit security checks)
ruff format src/ tests/          # Format
mypy src/ --strict               # Type checking

Melhores Práticas

Guias específicos de domínio para tarefas comuns de configuração de firewall:

Regras de Firewall para Chamadas do WhatsApp — Permita chamadas de voz/vídeo do WhatsApp através de um firewall de negação padrão usando aliases de tabela de URL e regras com escopo

Esses guias mostram padrões reais de uso das ferramentas MCP e explicam as considerações de segurança por trás de cada abordagem.

Contribuindo

Consulte CONTRIBUTING.md para diretrizes detalhadas. Pontos-chave:

Todos os testes devem usar respostas de API simuladas — nunca conecte a um OPNsense real
Sem ferramentas sobrepostas — cada ferramenta deve ter um propósito distinto
Escreva docstrings claras — elas são o único guia da IA para seleção de ferramentas
Retorne dados estruturados (dicionários), não strings formatadas
Execute make validate antes de enviar

Licença

MIT