OPNSense MCP Server

Gestiona firewalls OPNsense utilizando principios de Infraestructura como Código (IaC).

Documentación

Servidor MCP de OPNsense

Un servidor de Protocolo de Contexto de Modelo (MCP) para la gestión integral de firewalls OPNsense. Este servidor permite a asistentes de IA como Claude gestionar directamente configuraciones de firewall, diagnosticar problemas de red y automatizar tareas complejas de redes.

Características

🔥 Gestión de Firewall

Operaciones CRUD completas para reglas de firewall
Manejo adecuado de "reglas de automatización" creadas por API
Configuración de enrutamiento entre VLANs
Creación y gestión de reglas por lotes
Persistencia mejorada con múltiples métodos de respaldo

🌐 Configuración NAT (basada en SSH)

Gestión de reglas NAT de salida
Control del modo NAT (automático/híbrido/manual/deshabilitado)
Reglas de excepción No-NAT para tráfico entre VLANs
Resolución automatizada de problemas NAT en DMZ
Manipulación directa de configuración XML

🔍 Diagnóstico de Red

Análisis integral de enrutamiento
Inspección de tabla ARP con identificación de proveedor
Gestión de configuración de interfaces
Solución de problemas de conectividad de red
Capacidades de corrección automática para problemas comunes

🖥️ Ejecución SSH/CLI

Ejecución directa de comandos en OPNsense
Manipulación de archivos de configuración
Operaciones a nivel de sistema no disponibles vía API
Gestión y reinicio de servicios

📊 Capacidades Adicionales

Gestión de VLANs
Visualización y gestión de concesiones DHCP
Configuración de listas de bloqueo DNS
Soporte para balanceador de carga HAProxy
Respaldo y restauración de configuración
Soporte de Infraestructura como Código

Instalación

Requisitos previos

Node.js 18+ para ejecutar el servidor (Bun 1.1.39+ para desarrollarlo)
Firewall OPNsense (v24.7+ recomendado)
Credenciales de API para OPNsense
Acceso SSH (opcional, para funciones avanzadas)

Inicio rápido con npm

Instale el paquete:

npm install -g opnsense-mcp-server

Cree un archivo .env con sus credenciales:

# 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

Inicie el servidor MCP:

opnsense-mcp-server

⚠️ Modos de seguridad (léalo antes de apuntar a un router de producción)

Por defecto, este servidor puede realizar cambios inmediatos y en vivo en su firewall: agregar/eliminar reglas, cambiar NAT, reiniciar servicios, ejecutar comandos de shell en lista blanca a través de SSH. Dos variables de entorno (solo para operadores — una llamada de herramienta nunca puede establecerlas ni anularlas) añaden una red de seguridad:

Variable	Efecto
`OPNSENSE_READ_ONLY=true`	Cada llamada API mutante y cada comando SSH no solo de lectura se rechaza antes de enviarse. Las herramientas con capacidad de escritura también se ocultan de la lista de herramientas, por lo que el modelo nunca las ve como opción.
`OPNSENSE_DRY_RUN=true`	Las llamadas mutantes se simulan en lugar de enviarse: recibe una línea de registro y una respuesta de éxito sintética que describe lo que habría sucedido, sin que ninguna solicitud llegue al router.

Ambos se aplican en los dos puntos de estrangulamiento de nivel más bajo que este servidor usa para llegar al router: el cliente API y el ejecutor SSH, por lo que se aplican uniformemente en las más de 140 herramientas, no de forma individual. Si ambos están configurados, OPNSENSE_READ_ONLY gana.

# 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 la referencia de configuración, o docs/features/safety-modes.md para saber cómo funciona internamente.

Inicio rápido con Bun (más rápido)

Bun proporciona tiempos de inicio significativamente más rápidos y mejor rendimiento.

Instale Bun (si aún no está instalado):

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

Clone e instale:

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

Cree su archivo .env (igual que la versión npm anterior)
Ejecute con Bun:

# Development with hot reload
bun run dev:bun

# Production
bun run start:bun

Usar Bun con 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 con Claude Desktop (npm)

Agregue a su configuración de 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 comunes

Corregir problemas NAT en 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'
});

Crear reglas 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 enrutamiento

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

Ejecutar comandos CLI

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

Referencia de herramientas MCP

El servidor proporciona más de 50 herramientas MCP organizadas por categoría:

Herramientas de firewall

firewall_list_rules - Listar todas las reglas de firewall
firewall_create_rule - Crear una nueva regla
firewall_update_rule - Actualizar regla existente
firewall_delete_rule - Eliminar una regla
firewall_apply_changes - Aplicar cambios pendientes

Herramientas NAT

nat_list_outbound - Listar reglas NAT de salida
nat_set_mode - Establecer modo NAT
nat_create_outbound_rule - Crear regla NAT
nat_fix_dmz - Corregir problemas NAT en DMZ
nat_analyze_config - Analizar configuración NAT

Herramientas de red

arp_list - Listar entradas de tabla ARP
routing_diagnostics - Diagnosticar problemas de enrutamiento
routing_fix_all - Corregir automáticamente problemas de enrutamiento
interface_list - Listar interfaces de red
vlan_create - Crear VLAN

Herramientas de sistema

system_execute_command - Ejecutar comando CLI
backup_create - Crear respaldo de configuración
service_restart - Reiniciar un servicio

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

Documentación

Pruebas

El repositorio incluye utilidades integrales de prueba:

# 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

Desarrollo

Compilar desde el código fuente

Este repositorio usa Bun como su cadena de herramientas de desarrollo (instalación, compilación, pruebas). El paquete publicado sigue siendo Node.js puro — se consume como node dist/index.js — por lo que Bun solo se necesita para trabajar en el proyecto, no para ejecutarlo.

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

El archivo de bloqueo es bun.lock; no hay package-lock.json. CI ejecuta bun install --frozen-lockfile, así que confirme bun.lock junto con cualquier cambio de package.json.

Estructura del proyecto

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

Solución de problemas

Fallo de autenticación de API

Verifique que la clave y el secreto de API sean correctos
Asegúrese de que el acceso API esté habilitado en OPNsense
Verifique que las reglas de firewall permitan el acceso API

Fallo de conexión SSH

Verifique las credenciales SSH en .env
Asegúrese de que SSH esté habilitado en OPNsense
Verifique que el usuario tenga los privilegios adecuados

Funciones NAT que no funcionan

La gestión NAT requiere acceso SSH
Agregue credenciales SSH a las variables de entorno
Pruebe con: npx tsx scripts/test/test-nat-ssh.ts

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para las pautas.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENSE para más detalles.

Soporte

Problemas: Problemas de GitHub
Discusiones: Discusiones de GitHub
Documentación: Documentación completa

Agradecimientos

Construido para uso con Claude de Anthropic
Implementa el Protocolo de Contexto de Modelo
Diseñado para el firewall OPNsense

Versión: 0.8.2 | Estado: Listo para producción | Última actualización: Agosto 2025