mcp-pfsense

mcp-pfsense

Servidor MCP para gerenciar firewalls pfSense por meio de assistentes de IA como Claude, ChatGPT e Copilot.

Requer: pacote pfrest instalado na sua instância pfSense (fornece a API REST).

Recursos

19 ferramentas em 7 categorias:

Categoria	Ferramentas	Descrição
Sistema	get_system_status, get_interfaces	Versão, CPU, memória, tempo de atividade, temperatura, interfaces de rede
Firewall	list_firewall_rules, add_firewall_rule, delete_firewall_rule, list_firewall_aliases	Gerenciamento de regras com filtro por interface, listagem de aliases
DHCP	list_dhcp_leases, list_dhcp_static_mappings, add_dhcp_static_mapping, delete_dhcp_static_mapping	Concessões ativas, reservas de IP
DNS	list_dns_host_overrides, add_dns_host_override, delete_dns_host_override	Sobrescritas de host do Unbound DNS Resolver
Mudanças pendentes	get_pending_changes, apply_changes	Veja o que está em espera por subsistema (firewall, dhcp, dns) e aplique
Monitoramento	get_gateway_status, get_arp_table, list_services	Saúde do gateway, dispositivos conectados, status do serviço
Serviços	restart_service	Reinicie qualquer serviço do pfSense

Segurança

• Confirmação em duas etapas para operações destrutivas (excluir regras, excluir mapeamentos, reiniciar serviços, aplicar alterações): a ferramenta retorna um aviso na primeira chamada e só executa quando chamada novamente com confirm=true.
• As gravações são preparadas, não ativas. Como o WebGUI do pfSense, add_* e delete_* armazenam a alteração na configuração, mas não a ativam. A resposta da ferramenta informa isso (applied: false, além de uma nota pending). Ative com apply_changes(subsystem, confirm=true) — que recarrega aquele subsistema, incluindo qualquer coisa que um humano deixou preparada no WebGUI — ou passe apply=true na própria gravação quando você explicitamente quiser uma alteração única. Nada que o assistente faz chega ao filtro de pacotes sem uma dessas duas etapas explícitas.
• delete_dhcp_static_mapping usa o interface do mapeamento (seu parent_id em list_dhcp_static_mappings) e mapping_id; um mapeamento é endereçado por ambos.

Instalação

# Using uvx (recommended)
uvx mcp-pfsense

# Using pip
pip install mcp-pfsense

Pré-requisitos

1. pfSense com o pacote pfrest instalado
2. Uma conta de usuário com acesso à API (normalmente admin)

Configuração

Defina as variáveis de ambiente:

Variável	Obrigatória	Padrão	Descrição
PFSENSE_HOST	Sim	—	hostname ou IP do pfSense
PFSENSE_PASSWORD	Sim	—	senha do usuário da API
PFSENSE_USERNAME	Não	admin	nome de usuário da API
PFSENSE_PORT	Não	443	porta da API
PFSENSE_SCHEME	Não	https	http ou https
PFSENSE_VERIFY_SSL	Não	false	Verificar certificado SSL

Claude Desktop

Adicione a claude_desktop_config.json:

{
  "mcpServers": {
    "pfsense": {
      "command": "uvx",
      "args": ["mcp-pfsense"],
      "env": {
        "PFSENSE_HOST": "10.10.10.1",
        "PFSENSE_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add pfsense -- uvx mcp-pfsense

Em seguida, defina as variáveis de ambiente no seu shell ou no arquivo .env.

Exemplos de Uso

Depois de conectado, pergunte ao seu assistente de IA:

• "Qual é o status do sistema pfSense?"
• "Mostre-me todas as regras de firewall na interface LAN"
• "Liste as concessões DHCP ativas"
• "Adicione uma entrada DNS para nas.home.lan apontando para 10.10.10.50"
• "Quais dispositivos estão conectados à rede?" (tabela ARP)
• "Mostre a saúde do gateway e a latência"
• "Crie uma regra de firewall para permitir a porta TCP 8080 na LAN"
• "Reserve o IP 10.10.10.60 para o MAC aa:bb:cc:dd:ee:20"

Compatibilidade da API

• pfSense: 2.7.x e 2.8.x
• pfrest: API REST v2 — qualquer versão v2.x, exceto list_dhcp_static_mappings, que precisa de v2.7.0 ou posterior (usa o endpoint de coleção /services/dhcp_server/static_mappings adicionado nessa versão).
• Python: 3.11+

O endpoint, os parâmetros e a codificação que cada ferramenta usa são fixados por tests/test_client_endpoints.py e tests/test_wire_format.py, derivados das definições de endpoint do pfrest v2. Versões anteriores a 0.2.0 chamavam vários endpoints que não existem no pfrest v2 (veja Solução de Problemas).

Nota: o pfrest roda no nginx (porta 80 por padrão), separado do WebGUI do pfSense (lighttpd na porta 443). Se o seu pfrest estiver configurado em uma porta não padrão, defina PFSENSE_PORT e PFSENSE_SCHEME de acordo.

Solução de Problemas

Apenas get_system_status e get_arp_table funcionam; todo o resto retorna 400/404

mcp-pfsense 0.1.1 e anteriores chamavam endpoints singulares para listagem (/interface, /firewall/rule, /firewall/alias) e caminhos legados que o pfrest v2 não atende (/status/dhcp_leases, /services/dhcpd/static_mapping, /services/unbound/host_override, /status/gateway, /status/service para GET). Atualize para 0.2.0 ou posterior.

403 em list_services ou outras leituras

O pfrest verifica os privilégios do usuário da API por endpoint. Conceda ao usuário os privilégios api-v2-* para os endpoints que você precisa (ou page-all para acesso total) em System → User Manager.

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

O SDK Python do MCP 2.0 removeu o módulo que o mcp-pfsense 0.1.1 e anteriores importam, então instalações novas (uvx mcp-pfsense, pip install) falhavam na inicialização. Atualize para 0.2.0 ou posterior, que fixa mcp<2. Se você precisar permanecer em um mcp-pfsense mais antigo: uvx --with "mcp<2" mcp-pfsense.

Uma regra / mapeamento / sobrescrita foi criada, mas não está em vigor

Isso é o padrão: as gravações são preparadas (veja Segurança). Verifique com get_pending_changes(subsystem) e ative com apply_changes(subsystem, confirm=true), ou no WebGUI. Se uma gravação retornar 200 mas nada for armazenado, a configuração read_only do pfrest está ativada (System → REST API → Settings).

Desenvolvimento

git clone https://github.com/antonio-mello-ai/mcp-pfsense.git
cd mcp-pfsense
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint and type check
ruff check .
mypy src/

Licença

MIT