OPNSense MCP Server

Servidor MCP OPNsense

Um servidor Model Context Protocol (MCP) para gerenciamento abrangente de firewall OPNsense. Este servidor permite que assistentes de IA como o Claude gerenciem diretamente configurações de firewall, diagnostiquem problemas de rede e automatizem tarefas complexas de rede.

Recursos

🔥 Gerenciamento de Firewall

• Operações CRUD completas para regras de firewall
• Tratamento adequado de "regras de automação" criadas via API
• Configuração de roteamento entre VLANs
• Criação e gerenciamento de regras em lote
• Persistência aprimorada com múltiplos métodos de fallback

🌐 Configuração de NAT (baseada em SSH)

• Gerenciamento de regras de NAT de saída
• Controle do modo NAT (automático/híbrido/manual/desativado)
• Regras de exceção No-NAT para tráfego entre VLANs
• Resolução automatizada de problemas de NAT em DMZ
• Manipulação direta da configuração XML

🔍 Diagnóstico de Rede

• Análise abrangente de roteamento
• Inspeção da tabela ARP com identificação de fornecedor
• Gerenciamento de configuração de interfaces
• Solução de problemas de conectividade de rede
• Capacidades de correção automática para problemas comuns

🖥️ Execução SSH/CLI

• Execução direta de comandos no OPNsense
• Manipulação de arquivos de configuração
• Operações de nível de sistema não disponíveis via API
• Gerenciamento e reinicialização de serviços

📊 Capacidades Adicionais

• Gerenciamento de VLAN
• Visualização e gerenciamento de concessões DHCP
• Configuração de lista de bloqueio DNS
• Suporte a balanceador de carga HAProxy
• Backup e restauração de configuração
• Suporte a Infraestrutura como Código

Instalação

Pré-requisitos

• Node.js 18+ para executar o servidor (Bun 1.1.39+ para desenvolvimento)
• Firewall OPNsense (v24.7+ recomendado)
• Credenciais de API para OPNsense
• Acesso SSH (opcional, para recursos avançados)

Início Rápido com npm

1. Instale o pacote:

npm install -g opnsense-mcp-server

2. Crie um arquivo .env com suas credenciais:

# Required
OPNSENSE_HOST=https://your-opnsense-host:port
OPNSENSE_API_KEY=your-api-key
OPNSENSE_API_SECRET=your-api-secret
OPNSENSE_VERIFY_SSL=false

# Optional - for SSH features
OPNSENSE_SSH_HOST=your-opnsense-host
OPNSENSE_SSH_USERNAME=root
OPNSENSE_SSH_PASSWORD=your-password
# Or use SSH key
# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa

# Recommended for a new/production router — see "Safety Modes" below
# OPNSENSE_READ_ONLY=true

3. Inicie o servidor MCP:

opnsense-mcp-server

⚠️ Modos de Segurança (leia antes de apontar para um roteador de produção)

Por padrão, este servidor pode fazer alterações imediatas e ao vivo no seu firewall — adicionar/excluir regras, alterar NAT, reiniciar serviços, executar comandos shell na lista de permissões via SSH. Duas variáveis de ambiente (somente operador — uma chamada de ferramenta nunca pode defini-las ou sobrescrevê-las) adicionam uma rede de segurança:

Variável	Efeito
OPNSENSE_READ_ONLY=true	Toda chamada de API mutável e todo comando SSH não somente-leitura é rejeitado antes de ser enviado. Ferramentas com capacidade de escrita também são ocultadas da lista de ferramentas, então o modelo nunca as vê como opção.
OPNSENSE_DRY_RUN=true	Chamadas mutáveis são simuladas em vez de enviadas — você recebe uma linha de log e uma resposta de sucesso sintética descrevendo o que teria acontecido, sem que nenhuma requisição chegue ao roteador.

Ambos são aplicados nos dois pontos de estrangulamento de nível mais baixo que este servidor usa para alcançar o roteador — o cliente de API e o executor SSH — portanto, aplicam-se uniformemente a todas as 140+ ferramentas, não por ferramenta. Se ambos estiverem definidos, OPNSENSE_READ_ONLY vence.

# First time pointing this at a real router? Start here:
OPNSENSE_READ_ONLY=true

# Once you trust it, watch what it would do before going live:
OPNSENSE_DRY_RUN=true

# Remove both once you're confident.

Consulte CONFIGURATION.md para a referência de configuração, ou docs/features/safety-modes.md para saber como funciona internamente.

Início Rápido com Bun (Mais Rápido)

Bun oferece tempos de inicialização significativamente mais rápidos e melhor desempenho.

1. Instale o Bun (se ainda não estiver instalado):

curl -fsSL https://bun.sh/install | bash

2. Clone e instale:

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install

3. Crie seu arquivo .env (igual à versão npm acima)

4. Execute com Bun:

# Development with hot reload
bun run dev:bun

# Production
bun run start:bun

Usando Bun com Claude Desktop

{
  "mcpServers": {
    "opnsense": {
      "command": "bun",
      "args": ["run", "/path/to/OPNSenseMCP/src/index.ts"],
      "env": {
        "OPNSENSE_HOST": "https://your-opnsense:port",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Uso com Claude Desktop (npm)

Adicione à sua configuração do Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["opnsense-mcp-server"],
      "env": {
        "OPNSENSE_HOST": "https://your-opnsense:port",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Casos de Uso Comuns

Corrigir Problemas de NAT em DMZ

// Automatically fix DMZ to LAN routing
await mcp.call('nat_fix_dmz', {
  dmzNetwork: '10.0.6.0/24',
  lanNetwork: '10.0.0.0/24'
});

Criar Regras de Firewall

// Allow NFS from DMZ to NAS
await mcp.call('firewall_create_rule', {
  action: 'pass',
  interface: 'opt8',
  source: '10.0.6.0/24',
  destination: '10.0.0.14/32',
  protocol: 'tcp',
  destination_port: '2049',
  description: 'Allow NFS from DMZ'
});

Diagnosticar Problemas de Roteamento

// Run comprehensive routing diagnostics
await mcp.call('routing_diagnostics', {
  sourceNetwork: '10.0.6.0/24',
  destNetwork: '10.0.0.0/24'
});

Executar Comandos CLI

// Run any OPNsense CLI command
await mcp.call('system_execute_command', {
  command: 'pfctl -s state | grep 10.0.6'
});

Referência de Ferramentas MCP

O servidor fornece 50+ ferramentas MCP organizadas por categoria:

Ferramentas de Firewall

• firewall_list_rules - Listar todas as regras de firewall
• firewall_create_rule - Criar uma nova regra
• firewall_update_rule - Atualizar regra existente
• firewall_delete_rule - Excluir uma regra
• firewall_apply_changes - Aplicar alterações pendentes

Ferramentas de NAT

• nat_list_outbound - Listar regras de NAT de saída
• nat_set_mode - Definir modo NAT
• nat_create_outbound_rule - Criar regra NAT
• nat_fix_dmz - Corrigir problemas de NAT em DMZ
• nat_analyze_config - Analisar configuração NAT

Ferramentas de Rede

• arp_list - Listar entradas da tabela ARP
• routing_diagnostics - Diagnosticar problemas de roteamento
• routing_fix_all - Corrigir automaticamente problemas de roteamento
• interface_list - Listar interfaces de rede
• vlan_create - Criar VLAN

Ferramentas de Sistema

• system_execute_command - Executar comando CLI
• backup_create - Criar backup de configuração
• service_restart - Reiniciar um serviço

Para uma lista completa, consulte docs/api/mcp-tools.md.

Documentação

• Guia de Início Rápido
• Guia de Configuração
• Gerenciamento de NAT
• Execução SSH/CLI
• Regras de Firewall
• Modos de Segurança (Dry-Run e Somente Leitura)
• Solução de Problemas

Testes

O repositório inclui utilitários abrangentes de teste:

# Test NAT functionality
npx tsx scripts/test/test-nat-ssh.ts

# Test firewall rules
npx tsx scripts/test/test-rules.ts

# Test routing diagnostics
npx tsx scripts/test/test-routing.ts

# Run all tests
npm test

Desenvolvimento

Compilando a partir do Código Fonte

Este repositório usa Bun como sua cadeia de ferramentas de desenvolvimento (instalação, compilação, testes). O pacote publicado ainda é Node.js puro — é consumido como node dist/index.js — então o Bun é necessário apenas para trabalhar no projeto, não para executá-lo.

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install
bun run build
bun run test

O arquivo de bloqueio é bun.lock; não há package-lock.json. O CI executa bun install --frozen-lockfile, então confirme bun.lock junto com qualquer alteração em package.json.

Estrutura do Projeto

OPNSenseMCP/
├── src/                 # Source code
│   ├── api/            # API client
│   ├── resources/      # Resource implementations
│   └── index.ts        # MCP server entry
├── docs/               # Documentation
├── scripts/            # Utility scripts
│   ├── test/          # Test scripts
│   ├── debug/         # Debug utilities
│   └── fixes/         # Fix scripts
└── dist/               # Build output

Solução de Problemas

Falha na Autenticação da API

• Verifique se a chave e o segredo da API estão corretos
• Garanta que o acesso à API esteja habilitado no OPNsense
• Verifique se as regras de firewall permitem acesso à API

Falha na Conexão SSH

• Verifique as credenciais SSH em .env
• Garanta que o SSH esteja habilitado no OPNsense
• Verifique se o usuário tem privilégios apropriados

Recursos de NAT Não Funcionando

• O gerenciamento de NAT requer acesso SSH
• Adicione credenciais SSH às variáveis de ambiente
• Teste com: npx tsx scripts/test/test-nat-ssh.ts

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes.

Licença

Este projeto é licenciado sob a Licença MIT — consulte o arquivo LICENSE para detalhes.

Suporte

• Problemas: GitHub Issues
• Discussões: GitHub Discussions
• Documentação: Documentação Completa

Agradecimentos

• Construído para uso com Claude da Anthropic
• Implementa o Model Context Protocol
• Projetado para firewall OPNsense

---

Versão: 0.8.2 | Status: Pronto para Produção | Última Atualização: Agosto de 2025