OPNsense MCP Server

Um servidor MCP abrangente para gerenciar firewalls OPNsense, oferecendo mais de 300 ferramentas para configuração e monitoramento.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP OPNsense

Um servidor modular de Protocolo de Contexto de Modelo (MCP) que fornece 88 ferramentas baseadas em módulos, dando acesso a mais de 2000 métodos de gerenciamento de firewall OPNsense por meio de uma interface TypeScript com segurança de tipos.

Recursos

Arquitetura Modular - 88 ferramentas lógicas (uma por módulo) em vez de mais de 2000 ferramentas individuais
Cobertura Completa da API - Acesso a 752 métodos principais e 1271 métodos de plugins
Segurança de Tipos - Suporte completo a TypeScript com @richard-stovall/opnsense-typescript-client v0.5.3
Suporte a Plugins - Suporte opcional para 64 módulos de plugins
Organização Inteligente - Operações relacionadas agrupadas por módulo para facilitar a descoberta

O servidor MCP atua como uma ponte entre assistentes de IA (como o Claude Desktop) e seu firewall OPNsense, fornecendo acesso seguro à API por meio de uma interface de ferramentas modular.

Uso no Claude Desktop OPNsense MCP Server Network Architecture

Uso no Claude Code

Instalação

Como um Servidor MCP

Este pacote foi projetado para ser usado como um servidor MCP (Protocolo de Contexto de Modelo) com assistentes de IA como Claude Desktop, Cursor ou outros clientes compatíveis com MCP.

Pré-requisitos

Node.js 18 ou superior
Um firewall OPNsense com acesso à API habilitado
Chave e segredo de API da sua instalação OPNsense

Instalar a partir do npm

npm install -g @richard-stovall/opnsense-mcp-server

Uso como um Servidor MCP

Configuração do Claude Desktop

Adicione o seguinte ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Métodos Alternativos de Configuração

Usando Argumentos de Linha de Comando:

{
  "mcpServers": {
    "opnsense": {
      "command": "node",
      "args": [
        "/path/to/opnsense-mcp-server/index.js",
        "--url",
        "https://YOUR-OPNSENSE-IP",
        "--api-key",
        "YOUR-API-KEY",
        "--api-secret",
        "YOUR-API-SECRET",
        "--no-verify-ssl"
      ]
    }
  }
}

Habilitar Ferramentas de Plugins: Para incluir todas as 64 ferramentas de módulos de plugins, adicione "--plugins" aos argumentos ou defina "INCLUDE_PLUGINS": "true" no ambiente.

Testando a Configuração

Após configurado, você pode testar a conexão perguntando ao Claude:

"Quais ferramentas MCP estão disponíveis?"
"Use core_manage para obter o status do sistema"
"Use firewall_manage para pesquisar todos os aliases"
"Use interfaces_manage para listar todas as interfaces de rede"

Solução de Problemas na Configuração do Claude Desktop

Problemas de Conexão:

Verifique se a API do OPNsense está habilitada
Confirme se a chave de API tem as permissões adequadas
Garanta que o IP/nome do host esteja acessível a partir da sua máquina
Para certificados autoassinados, use --no-verify-ssl ou defina "OPNSENSE_VERIFY_SSL": "false"

Visualizar Logs do Servidor: Verifique os logs do Claude Desktop para mensagens de erro do servidor MCP.

Testar Manualmente: Você pode testar o servidor manualmente antes de usar com o Claude Desktop:

node /path/to/opnsense-mcp-server/index.js \
  --url https://YOUR-OPNSENSE-IP \
  --api-key YOUR-API-KEY \
  --api-secret YOUR-API-SECRET \
  --no-verify-ssl

Isso deve exibir:

OPNsense MCP server v0.6.0 (modular) started
Core tools: 24 modules
Plugin tools: 64 modules (disabled)
Total available: 24 modules

Configuração do Cursor

Adicione às configurações do Cursor (.cursor/mcp.json no seu projeto ou ~/.cursor/mcp.json globalmente):

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Opções de Configuração

O servidor aceita configuração por meio de variáveis de ambiente:

OPNSENSE_URL - URL do host OPNsense (obrigatório)
OPNSENSE_API_KEY - Chave de API para autenticação (obrigatório)
OPNSENSE_API_SECRET - Segredo da API para autenticação (obrigatório)
INCLUDE_PLUGINS - Defina como "true" para habilitar 64 ferramentas de módulos de plugins (opcional)
OPNSENSE_VERIFY_SSL - Defina como "false" para desabilitar a verificação SSL (apenas desenvolvimento)

Como Funciona

O servidor MCP modular fornece ao seu assistente de IA 88 ferramentas baseadas em módulos. Cada ferramenta representa um módulo OPNsense e aceita um parâmetro method para especificar a operação.

Padrão de Uso da Ferramenta:

{
  "tool": "firewall_manage",
  "arguments": {
    "method": "aliasSearchItem",
    "params": {
      "searchPhrase": "web"
    }
  }
}

Exemplos de prompts:

"Use core_manage para verificar o status do sistema"
"Use firewall_manage para listar todos os aliases de firewall"
"Use interfaces_manage para obter informações da interface de rede"
"Use plugin_nginx_manage para verificar a configuração do servidor web"
"Use diagnostics_manage para visualizar a tabela ARP"

A abordagem modular facilita a descoberta de funcionalidades relacionadas - todas as operações de firewall estão em firewall_manage, todas as operações de VPN em seus respectivos módulos (openvpn_manage, ipsec_manage, wireguard_manage).

Ferramentas de Módulos Disponíveis

Módulos Principais (24 ferramentas)

Cada ferramenta fornece acesso a todos os métodos dentro desse módulo:

Nome da Ferramenta	Descrição	Exemplos de Métodos
`core_manage`	Funções principais do sistema	`backupBackups`, `systemReboot`, `firmwareInfo`
`firewall_manage`	Regras e aliases de firewall	`aliasSearchItem`, `filterAddRule`, `natSearchRule`
`interfaces_manage`	Interfaces de rede	`getInterfaces`, `vlanAddItem`, `setInterface`
`diagnostics_manage`	Diagnóstico do sistema	`interfaceGetArp`, `systemActivityGetActivity`
`auth_manage`	Autenticação	`userSearchUser`, `groupSearchGroup`
`firmware_manage`	Atualizações de firmware	`check`, `update`, `upgrade`, `changelog`
`openvpn_manage`	OpenVPN	`instancesSearch`, `instancesAdd`, `serviceReconfigure`
`ipsec_manage`	VPN IPsec	`tunnelSearchPhase1`, `connectionStatus`
`wireguard_manage`	VPN WireGuard	`serverSearchServer`, `clientSearchClient`
`unbound_manage`	Resolvedor DNS	`hostOverrideSearchItem`, `serviceReconfigure`
`dhcpv4_manage`	Servidor DHCP	`searchLease`, `addReservation`

Módulos de Plugins (64 ferramentas quando habilitados)

Módulos de plugins populares:

Nome da Ferramenta	Descrição	Exemplos de Métodos
`plugin_nginx_manage`	Servidor web Nginx	`generalGet`, `upstreamSearchUpstream`
`plugin_haproxy_manage`	Balanceador de carga HAProxy	`serverSearchServer`, `statsGet`
`plugin_caddy_manage`	Servidor web Caddy	`reverseProxySearchDomain`, `serviceStatus`
`plugin_bind_manage`	DNS BIND	`domainSearchDomain`, `recordSearchRecord`
`plugin_acmeclient_manage`	Let's Encrypt	`certificatesSearch`, `certificatesIssue`

Compilando a partir do Código-Fonte

Se você quiser contribuir ou personalizar o servidor:

# Clone the repository
git clone https://github.com/richard-stovall/opnsense-mcp-server.git
cd opnsense-mcp-server

# Install dependencies with Yarn 4.9.2
yarn install

# Build the project
yarn build

# Run locally
yarn start

Desenvolvimento

Scripts de Desenvolvimento

yarn generate-tools  # Generate tool definitions
yarn build          # Build the server
yarn build:all      # Generate tools and build
yarn dev            # Run with hot reload
yarn type-check     # Type check without emitting
yarn start          # Start the server

Pilha de Tecnologia

Runtime: Node.js com tsx para execução TypeScript
Gerenciador de Pacotes: Yarn 4.9.2 com Plug'n'Play
Sistema de Build: Compilação TypeScript simples para arquivo único
Linguagem: TypeScript 5.3+
SDK MCP: @modelcontextprotocol/sdk
Cliente de API: @richard-stovall/opnsense-typescript-client
Validação: Zod para validação de esquemas
Testes: Jest com suporte a TypeScript

Integração com a API

O servidor usa o pacote @richard-stovall/opnsense-typescript-client, que fornece:

Segurança completa de tipos para todas as chamadas de API
Tratamento de erros e novas tentativas integrados
Suporte para todos os 601 endpoints da API OPNsense
Implementação baseada na API Fetch moderna

Exemplo de Implementação de Ferramenta

const response = await client.system.getStatus();
return {
  content: [
    {
      type: 'text',
      text: JSON.stringify(response.data, null, 2),
    },
  ],
};

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Faça um fork do repositório
Crie sua branch de recurso (git checkout -b feature/AmazingFeature)
Faça commit das suas alterações (git commit -m 'Add some AmazingFeature')
Envie para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Agradecimentos

Construído sobre o Protocolo de Contexto de Modelo da Anthropic
Desenvolvido com @richard-stovall/opnsense-typescript-client
Inspirado pela comunidade OPNsense

Feito com amor para a comunidade OPNsense