OPNsense MCP Server

Un servidor seguro del Model Context Protocol (MCP) para gestionar cortafuegos OPNsense mediante asistentes de IA como Claude Code, Cursor y otras herramientas compatibles con MCP.

81 herramientas en 10 dominios: sistema, cortafuegos, red, DNS, DHCP, VPN, HAProxy, servicios, diagnósticos y seguridad.

Requisitos

• Python 3.11+

• OPNsense 24.7 o superior — el servidor MCP se basa en los endpoints de API basados en MVC introducidos en OPNsense 24.7. Las versiones anteriores usan una estructura de API diferente que no es compatible. El servidor detecta automáticamente la versión de OPNsense en la primera conexión y selecciona la nomenclatura de endpoints correcta (camelCase para versiones anteriores a 25.7, snake_case para 25.7+). OPNsense 26.x es totalmente compatible, incluido su formato de respuesta de estado de firmware modificado.

Related MCP server: OPNsense MCP Server

Modelo de Seguridad

Este servidor MCP está diseñado con la seguridad como principal preocupación:

• Solo lectura por defecto — las operaciones de escritura requieren una aceptación explícita mediante OPNSENSE_ALLOW_WRITES=true

• Savepoint/rollback (solo OPNsense < 26.7) — donde OPNsense aún ofrece la API de savepoint, las modificaciones del cortafuegos usan su reversión automática integrada de 60 segundos; los cambios deben confirmarse explícitamente o se revierten automáticamente. OPNsense 26.7 eliminó esa API en el proyecto original — el servidor detecta el endpoint faltante en tiempo de ejecución y aplica los cambios del cortafuegos de inmediato, sin reversión automática

• Lista de bloqueo de endpoints — los endpoints peligrosos (halt, reboot, poweroff, firmware update/upgrade) están bloqueados de forma permanente a nivel del cliente de API y nunca pueden invocarse

• Solo API — no hay acceso SSH, no hay ejecución de comandos, no hay manipulación directa de archivos de configuración

• Transporte local — solo STDIO, sin endpoints HTTP/SSE expuestos a la red

• Sin exposición de credenciales — las claves de API nunca se incluyen en la salida de las herramientas, los registros ni los mensajes de error

• Validación de entrada — los parámetros de nombre de host se validan contra la inyección de metacaracteres de shell

• Eliminación de datos sensibles — la copia de seguridad de configuración elimina contraseñas y claves por defecto

Inicio Rápido

1. Crea una clave de API de OPNsense

1. Inicia sesión en la interfaz web de OPNsense

2. Ve a System > Access > Users

3. Edita un usuario existente o crea un usuario de API dedicado:

   • Para uso en producción, crea un usuario dedicado (p. ej., mcp-api) con solo los privilegios necesarios

   • Para acceso de solo lectura, asigna el usuario a un grupo con acceso de API de solo lectura

4. Desplázate hasta la sección API keys y haz clic en el botón +

5. Se generará un par clave/secreto y se descargará un archivo (apikey.txt)

6. El archivo contiene dos líneas — key=your-api-key-here y secret=your-api-secret-here

7. Guarda estas credenciales de forma segura — el secreto no se puede recuperar de nuevo desde OPNsense

Consejo: Para una configuración de solo lectura (recomendada para empezar), no necesitas cambiar ningún permiso — el acceso de API por defecto es suficiente para todas las herramientas de solo lectura.

2. Instalación

# 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 .

Imagen de Docker: la imagen oficial es uhlenheide/opnsense-mcp-server, publicada desde este repositorio por .github/workflows/publish-docker.yml en cada etiqueta v*. No existe ninguna imagen lucamarien/opnsense-mcp-server — versiones anteriores del README la mencionaban por error.

3. Configura tu asistente de IA

Claude Code

Añádelo a .mcp.json de tu proyecto:

{
  "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: Usa "command": "python", "args": ["-m", "opnsense_mcp"] si el CLI opnsense-mcp no está en tu PATH.

O añádelo globalmente a ~/.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

Añádelo a la configuración de MCP de 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"
      }
    }
  }
}

Configuración

Puertos personalizados: Si la interfaz web de OPNsense se ejecuta en un puerto no estándar (p. ej., 10443), inclúyelo en la URL: https://192.168.1.1:10443/api

Herramientas disponibles (81)

Sistema (7 herramientas)

Red (5 herramientas)

Cortafuegos (21 herramientas)

Nota: La protección de punto de restauración solo existe en OPNsense < 26.7. En 26.7+ estas herramientas aplican cambios inmediatamente y de forma permanente — ver Operaciones de escritura y puntos de restauración.

DNS (13 herramientas)

DHCP (8 herramientas)

VPN (3 herramientas)

HAProxy (8 herramientas)

Gestión completa de la configuración del balanceador de carga HAProxy (requiere el plugin os-haproxy).

Nota: Los cambios de HAProxy NO utilizan protección de savepoint: se aplican inmediatamente al reconfigurar. Llame siempre a opn_haproxy_configtest antes de opn_reconfigure_haproxy.

Servicios (11 herramientas)

Diagnóstico (4 herramientas)

Seguridad (1 herramienta)

Operaciones de escritura y savepoints

Las operaciones de escritura requieren OPNSENSE_ALLOW_WRITES=true. En OPNsense < 26.7, los cambios de firewall pasan además por el mecanismo de savepoint de OPNsense:

1. Antes de cualquier cambio de firewall, se crea un savepoint automáticamente

2. Se aplica el cambio (activar/desactivar regla, añadir o eliminar)

3. Comienza una cuenta atrás de 60 segundos: si no se confirma, OPNsense revierte el cambio automáticamente

4. Use opn_confirm_changes con la revision devuelta para hacer los cambios permanentes

En esas versiones, si un asistente de IA realiza un cambio de firewall incorrecto que le bloquea el acceso, el cambio se revierte automáticamente en 60 segundos.

OPNsense 26.7 eliminó la API de savepoint/rollback en upstream, por lo que no hay reversión automática en 26.7+. El servidor no fija un límite de versión codificado: sondea el endpoint de savepoint en la primera escritura de firewall y, si OPNsense responde que el endpoint no existe, degrada a aplicación directa durante el resto de la sesión. Consulte opn_mcp_info: su campo savepoint_support informa true, false o null si aún no se ha probado ninguna escritura. Las herramientas de escritura devuelven entonces una revision vacía, opn_confirm_changes responde con status: "not_applicable", y cada cambio de firewall es inmediato y permanente.

Advertencia: En OPNsense 26.7+ haga una copia de seguridad de la configuración (opn_download_config, o Sistema > Configuración > Copias de seguridad) antes de habilitar las escrituras, y mantenga acceso fuera de banda al equipo: una regla que le bloquee el acceso no se revertirá por sí sola.

Nota: opn_reconfigure_unbound, opn_reconfigure_haproxy, opn_reconfigure_ddclient, opn_reconfigure_dnsmasq y opn_configure_mdns_repeater requieren escrituras pero no usan savepoints: aplican cambios de configuración de servicios y no son revertibles automáticamente.

Soporte IPv6

Totalmente automatizado mediante MCP

• Reglas de firewall IPv6 — Cree reglas con ip_protocol="inet6" (protegidas por savepoint en OPNsense < 26.7)

• Bindings de HAProxy IPv6 — Frontends con direcciones de bind [::]:443 o [2001:db8::1]:443

• Backends de HAProxy IPv6 — Servidores con direcciones IPv6, resolvePrefer: ipv6 en backends

• Dynamic DNS con IPv6 — Cuentas DDNS con métodos checkip compatibles con IPv6

• Rangos DHCPv6 (dnsmasq) — Rangos DHCP IPv6 con configuración de Router Advertisement

• Registros DNS AAAA — Host overrides de Unbound con direcciones IPv6

• Diagnósticos IPv6 — Traceroute con ip_version="6", ping mediante nombre de host

Requiere configuración manual mediante GUI

Estos ajustes carecen de soporte de API MVC en OPNsense y deben configurarse a través de la GUI web:

• Configuración de WAN IPv6 — PPPoE con delegación de prefijo DHCPv6, IPv6 estático, SLAAC

• Direccionamiento IPv6 de LAN — Modo Track Interface, asignación estática /64, ID de prefijo

• Asignación de interfaces — Asignación de puertos físicos a roles WAN/LAN/OPT

• Túneles 6to4/6rd — Mecanismos de túnel de transición

Limitaciones conocidas

• ISC DHCP / Kea DHCPv6: No implementado. Solo dnsmasq (el predeterminado moderno) es compatible con rangos DHCPv6 y Router Advertisements. ISC DHCP está obsoleto; la visibilidad de concesiones de Kea DHCPv6 es limitada en la API.

• radvd: No implementado como un conjunto de herramientas independiente. Dnsmasq maneja Router Advertisements de forma nativa mediante la configuración de rangos. Solo debe ejecutarse un demonio RA por interfaz.

• Reglas de firewall de doble pila: inet46 (doble pila) funciona correctamente en reglas de API MVC (opn_add_firewall_rule). Sin embargo, inet46 en reglas de filtro XML heredadas (GUI) no genera ninguna salida PF de forma silenciosa; este es un bug conocido de OPNsense que solo afecta a las reglas heredadas.

• Reglas de GUI heredadas: Las reglas de firewall creadas mediante la GUI tradicional de OPNsense no son accesibles a través de la API MVC. Use opn_get_config_section("filter") para acceso de solo lectura.

Flujo de trabajo recomendado para la migración a IPv6

1. Manual (GUI): Configurar WAN IPv6 (DHCPv6-PD del ISP o estático)

2. Manual (GUI): Configurar interfaces LAN (modo Track Interface para delegación de prefijos)

3. MCP: Configurar Router Advertisements mediante opn_add_dnsmasq_range con flags de RA

4. MCP: Crear reglas de firewall IPv6 (se debe permitir ICMPv6 para NDP/RA/PMTUD)

5. MCP: Añadir registros DNS IPv6 mediante opn_add_dns_override

6. MCP: Configurar Dynamic DNS con el método checkip IPv6

7. MCP: Añadir direcciones de bind IPv6 a los frontends de HAProxy

8. MCP: Verificar con opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status

Compatibilidad de versiones

El servidor detecta automáticamente la versión de OPNsense en la primera conexión y selecciona la convención de nomenclatura correcta de los endpoints de la API (camelCase para versiones anteriores a 25.7, snake_case para 25.7+).

Nota sobre reglas de firewall: opn_list_firewall_rules muestra las reglas gestionadas mediante la API MVC/automatización. Las reglas configuradas a través de la GUI de OPNsense usan un formato heredado no accesible mediante esta API. Esta es una limitación conocida de OPNsense.

Solución de problemas

Problemas de conexión

Errores de «Connection refused» o de tiempo de espera agotado

• Verifique que OPNSENSE_URL termine en /api (p. ej., https://192.168.1.1/api)

• Si usa un puerto no estándar, inclúyalo: https://192.168.1.1:10443/api

• Asegúrese de que la GUI web de OPNsense sea accesible desde la máquina que ejecuta el servidor MCP

Errores de certificado SSL

• Para certificados autofirmados (configuración predeterminada de OPNsense), establezca OPNSENSE_VERIFY_SSL=false

• Para producción, instale un certificado adecuado en OPNsense y mantenga OPNSENSE_VERIFY_SSL=true

Problemas de autenticación

401 No autorizado

• Verifique que OPNSENSE_API_KEY y OPNSENSE_API_SECRET sean correctos

• Las claves de API distinguen entre mayúsculas y minúsculas: cópielas exactamente del archivo apikey.txt descargado

• Compruebe que el usuario de la API no esté deshabilitado en OPNsense

• Verifique que el usuario de la API tenga privilegios suficientes para las operaciones que está intentando realizar

403 Prohibido

• El usuario de la API puede carecer de permisos para el endpoint solicitado

• Para operaciones de escritura, asegúrese de que OPNSENSE_ALLOW_WRITES=true esté configurado

Problemas específicos de herramientas

opn_list_firewall_rules devuelve resultados vacíos

• Esta herramienta solo muestra reglas de MVC/automatización, no reglas de GUI heredadas

• Cree reglas mediante la API de automatización o opn_add_firewall_rule para verlas

opn_ping agota el tiempo de espera

• Es posible que el firewall no tenga una ruta al host de destino

• Compruebe el estado de la puerta de enlace con opn_gateway_status

• El tiempo de espera predeterminado es de 30 segundos (30 ciclos de sondeo)

opn_download_config muestra valores [REDACTED]

• Este es el comportamiento predeterminado por motivos de seguridad. Pase include_sensitive=true para incluir contraseñas y claves (úselo con precaución en conversaciones con IA)

Las operaciones de escritura fallan con «writes not enabled»

• Establezca OPNSENSE_ALLOW_WRITES=true en la configuración de su servidor MCP

• Por seguridad, está deshabilitado intencionalmente de forma predeterminada

La confirmación de savepoint falla

• El parámetro revision debe coincidir exactamente con lo que devolvió la operación de escritura

• Las confirmaciones deben realizarse dentro de 60 segundos o el cambio se revierte automáticamente

• En OPNsense 26.7+ no hay API de savepoint: las herramientas de escritura devuelven una revision vacía y opn_confirm_changes devuelve status: "not_applicable". Esto es lo esperado, no un fallo — el cambio ya se ha aplicado de forma permanente

Comandos de diagnóstico

Si necesita depurar el 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

Desarrollo

# 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

Buenas prácticas

Guías específicas de dominio para tareas comunes de configuración de firewall:

• Reglas de firewall para llamadas de WhatsApp — Permite llamadas de voz/vídeo de WhatsApp a través de un firewall de denegación predeterminada usando alias de tabla URL y reglas con ámbito

Estas guías muestran patrones de uso reales de las herramientas MCP y explican las consideraciones de seguridad detrás de cada enfoque.

Contribuciones

Consulte CONTRIBUTING.md para obtener pautas detalladas. Puntos clave:

1. Todas las pruebas deben usar respuestas de API simuladas — nunca se conecte a un OPNsense real

2. Sin herramientas superpuestas — cada herramienta debe tener un propósito distinto

3. Escriba docstrings claros — son la única guía de la IA para la selección de herramientas

4. Devuelva datos estructurados (diccionarios), no cadenas formateadas

5. Ejecute make validate antes de enviar

Licencia

MIT