OPNsense MCP Server

Servidor MCP de OPNsense

Un servidor Model Context Protocol (MCP) seguro para gestionar cortafuegos OPNsense a través de 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 posterior — el servidor MCP depende de los endpoints de API basados en MVC introducidos en OPNsense 24.7. Las versiones anteriores utilizan 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.

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
• Punto de guardado/rollback (solo OPNsense < 26.7) — donde OPNsense aún ofrece la API de punto de guardado, las modificaciones del cortafuegos utilizan 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 upstream — el servidor detecta el endpoint faltante en tiempo de ejecución y aplica los cambios del cortafuegos inmediatamente, 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 ser invocados
• Solo API — sin acceso SSH, sin ejecución de comandos, sin 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 herramientas, registros o 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. Crear una clave de API de OPNsense

1. Inicie sesión en la interfaz web de OPNsense
2. Vaya a Sistema > Acceso > Usuarios
3. Edite un usuario existente o cree un usuario de API dedicado:
   • Para uso en producción, cree un usuario dedicado (p. ej., mcp-api) con solo los privilegios necesarios
   • Para acceso de solo lectura, asigne el usuario a un grupo con acceso de API de solo lectura
4. Desplácese hasta la sección Claves de API y haga 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. Almacene estas credenciales de forma segura — el secreto no se puede recuperar nuevamente desde OPNsense

Consejo: Para una configuración de solo lectura (recomendada para comenzar), no necesita cambiar ningún permiso — el acceso de API predeterminado 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 una imagen lucamarien/opnsense-mcp-server — las versiones anteriores del README la nombraron por error.

3. Configurar su asistente de IA

Claude Code

Agregue al .mcp.json de su 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: Use "command": "python", "args": ["-m", "opnsense_mcp"] si la CLI de opnsense-mcp no está en su PATH.

O agréguelo 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

Agregue a la configuración de MCP de Cursor (Configuración > 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

Variable de entorno	Predeterminado	Descripción
OPNSENSE_URL	(obligatorio)	URL base de la API de OPNsense (debe terminar con /api)
OPNSENSE_API_KEY	(obligatorio)	Clave de API de la configuración de usuario de OPNsense
OPNSENSE_API_SECRET	(obligatorio)	Secreto de API de la configuración de usuario de OPNsense
OPNSENSE_VERIFY_SSL	true	Verificar certificado SSL (false para certificados autofirmados)
OPNSENSE_ALLOW_WRITES	false	Habilitar operaciones de escritura (reglas de cortafuegos, control de servicios)

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

Herramientas disponibles (81)

Sistema (7 herramientas)

Herramienta	Descripción
opn_system_status	Información del sistema, incluida la versión de firmware, nombre del producto y arquitectura
opn_list_services	Listar todos los servicios y su estado de ejecución. Parámetros: search, limit
opn_gateway_status	Disponibilidad de puerta de enlace, latencia y comprobaciones de salud de dpinger
opn_download_config	Descargar copia de seguridad config.xml con eliminación opcional de datos sensibles. Parámetros: include_sensitive (predeterminado: false — las contraseñas y claves están redactadas)
opn_scan_config	Escanear la configuración completa, analizarla en secciones y recopilar inventario de tiempo de ejecución (firmware, complementos, DHCP, DNS, interfaces, servicios). Los resultados se almacenan en caché por sesión. Parámetros: force
opn_get_config_section	Obtener una sección de configuración específica como JSON estructurado. Parámetros: section, include_sensitive
opn_mcp_info	Versión del servidor MCP, estado del modo de escritura, versión de OPNsense detectada, estilo de API y si las escrituras del cortafuegos aún tienen protección de punto de guardado/rollback

Red (5 herramientas)

Herramienta	Descripción
opn_interface_stats	Estadísticas de tráfico por interfaz (bytes de entrada/salida, paquetes, errores)
opn_arp_table	Tabla ARP que muestra asignaciones de IP a MAC
opn_ndp_table	Tabla NDP (Protocolo de descubrimiento de vecinos) que muestra asignaciones de IPv6 a MAC
opn_ipv6_status	Configuración IPv6 y estado de direcciones para todas las interfaces (método, direcciones activas, resumen)
opn_list_static_routes	Rutas estáticas configuradas. Parámetros: search, limit

Cortafuegos (21 herramientas)

Herramienta	Descripción	Escrituras
opn_list_firewall_rules	Listar reglas de filtro del cortafuegos MVC. Parámetros: search, limit	No
opn_list_firewall_aliases	Listar definiciones de alias (listas IP, grupos de puertos, GeoIP, URL). Parámetros: search, limit	No
opn_list_nat_rules	Listar reglas de reenvío de puertos NAT (DNAT). Parámetros: search, limit	No
opn_list_firewall_categories	Listar categorías de reglas del cortafuegos y sus UUID. Parámetros: search, limit	No
opn_firewall_log	Entradas recientes del registro del cortafuegos con filtrado del lado del cliente. Parámetros: source_ip, destination_ip, action, interface, limit	No
opn_confirm_changes	Confirmar cambios pendientes, cancelando la reversión automática de 60 segundos (OPNsense < 26.7; una operación sin efecto que devuelve not_applicable en 26.7+). Parámetros: revision	Sí
opn_toggle_firewall_rule	Alternar el estado habilitado/deshabilitado de una regla con punto de guardado (OPNsense < 26.7). Parámetros: uuid	Sí
opn_add_firewall_rule	Crear una nueva regla de filtro con punto de guardado (OPNsense < 26.7). Parámetros: action, direction, interface, ip_protocol, protocol, source_net, destination_net, destination_port, description	Sí
opn_delete_firewall_rule	Eliminar una regla de filtro por UUID con punto de guardado (OPNsense < 26.7). Parámetros: uuid	Sí
opn_add_alias	Crear un nuevo alias. Parámetros: name, alias_type, content, description	Sí
opn_add_nat_rule	Crear una regla de reenvío de puertos NAT con punto de guardado (OPNsense < 26.7). Parámetros: destination_port, target_ip, interface, protocol, target_port, description	Sí
opn_add_firewall_category	Crear una nueva categoría de reglas del cortafuegos. Parámetros: name, color	Sí
opn_delete_firewall_category	Eliminar una categoría de reglas del cortafuegos por UUID con punto de guardado (OPNsense < 26.7). Parámetros: uuid	Sí
opn_set_rule_categories	Asignar categorías a una regla del cortafuegos con punto de guardado (OPNsense < 26.7). Parámetros: uuid, categories	Sí
opn_add_icmpv6_rules	Crear reglas ICMPv6 esenciales requeridas para la operación IPv6 (NDP, RA, ping6) según RFC 4890. Parámetros: interface	Sí
opn_update_alias	Actualizar un alias existente (nombre, contenido, tipo, descripción). Lectura-modificación-escritura. Parámetros: uuid, name, content, description, alias_type, enabled	Sí
opn_delete_alias	Eliminar un alias por UUID. Verificar referencias de reglas primero. Parámetros: uuid	Sí
opn_toggle_alias	Alternar el estado habilitado/deshabilitado del alias. Parámetros: uuid	Sí
opn_update_firewall_rule	Actualizar campos de reglas de filtro con punto de guardado (OPNsense < 26.7). Parámetros: uuid, action, direction, interface, ip_protocol, protocol, source_net, source_not, source_port, destination_net, destination_not, destination_port, gateway, log, quick, sequence, categories, description, enabled	Sí
opn_update_nat_rule	Actualizar regla de reenvío de puertos NAT con punto de guardado (OPNsense < 26.7). Parámetros: uuid, interface, protocol, destination_port, target_ip, target_port, description, enabled	Sí
opn_delete_nat_rule	Eliminar una regla de reenvío de puertos NAT por UUID con punto de guardado (OPNsense < 26.7). Parámetros: uuid	Sí

Nota: La protección de punto de guardado solo existe en OPNsense < 26.7. En 26.7+ estas herramientas aplican los cambios inmediata y permanentemente — consulte Operaciones de escritura y puntos de guardado.

DNS (13 herramientas)

Herramienta	Descripción	Escrituras
opn_list_dns_overrides	Anulaciones de host de Unbound (registros DNS locales). Parámetros: search, limit	No
opn_list_dns_forwards	Zonas de reenvío de DNS (servidores específicos de dominio). Parámetros: search, limit	No
opn_dns_stats	Estadísticas del resolutor de Unbound (consultas, aciertos de caché, tiempo de actividad)	No
opn_reconfigure_unbound	Aplicar cambios pendientes de configuración del resolutor de DNS	Sí
opn_add_dns_override	Agregar una anulación de host DNS de Unbound (registro A/AAAA) y aplicar inmediatamente. Parámetros: hostname, domain, server, description	Sí
opn_list_dnsbl	Listar configuraciones de listas de bloqueo DNSBL con proveedores y estado. Parámetros: search, limit	No
opn_get_dnsbl	Obtener configuración completa de DNSBL por UUID (proveedores, listas permitidas, configuraciones). Parámetros: uuid	No
opn_set_dnsbl	Actualizar configuraciones de DNSBL (lectura-modificación-escritura). Parámetros: uuid, enabled, providers, allowlists, blocklists, wildcards, etc.	Sí
opn_add_dnsbl_allowlist	Agregar dominios a la lista permitida de DNSBL sin sobrescribir. Parámetros: uuid, domains	Sí
opn_remove_dnsbl_allowlist	Eliminar dominios de la lista permitida de DNSBL. Parámetros: uuid, domains	Sí
opn_update_dnsbl	Recargar archivos de listas de bloqueo DNSBL y reiniciar Unbound (sin cambio de configuración, herramienta de recuperación)	Sí
opn_update_dns_override	Actualizar una anulación de host DNS de Unbound y aplicar inmediatamente. Parámetros: uuid, hostname, domain, server, description, enabled	Sí
opn_delete_dns_override	Eliminar una anulación de host DNS de Unbound y aplicar inmediatamente. Parámetros: uuid	Sí

DHCP (8 herramientas)

Herramienta	Descripción	Escribe
opn_list_dhcp_leases	Concesiones DHCPv4 activas del servidor ISC DHCP	No
opn_list_kea_leases	Concesiones DHCPv4 del servidor DHCP Kea. Parámetros: search, limit	No
opn_list_dnsmasq_leases	Concesiones DHCPv4 y DHCPv6 del servidor DNS/DHCP dnsmasq. Parámetros: search, limit	No
opn_list_dnsmasq_ranges	Rangos de direcciones DHCP configurados (tanto DHCPv4 como DHCPv6 con configuración RA). Parámetros: search, limit	No
opn_add_dnsmasq_range	Crear un nuevo rango DHCP (IPv4 o IPv6 con configuración de Router Advertisement). Parámetros: interface, start_addr, end_addr, prefix_len, ra_mode, lease_time, description	Sí
opn_reconfigure_dnsmasq	Aplicar cambios de configuración DNS/DHCP de dnsmasq pendientes	Sí
opn_update_dnsmasq_range	Actualizar un rango DHCP (direcciones, tiempo de concesión, configuración RA) y aplicar. Parámetros: uuid, interface, start_addr, end_addr, prefix_len, ra_mode, lease_time, description, enabled	Sí
opn_delete_dnsmasq_range	Eliminar un rango DHCP por UUID y aplicar. Parámetros: uuid	Sí

VPN (3 herramientas)

Herramienta	Descripción
opn_wireguard_status	Estado de túneles y pares WireGuard (requiere el plugin os-wireguard)
opn_ipsec_status	Estado de túneles VPN IPsec — sesiones IKE (Fase 1) y ESP/AH (Fase 2)
opn_openvpn_status	Estado de conexiones OpenVPN — instancias, sesiones y rutas

HAProxy (8 herramientas)

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

Herramienta	Descripción	Escribe
opn_haproxy_status	Estado del servicio HAProxy y salud de los backends	No
opn_haproxy_search	Buscar recursos HAProxy por tipo. Parámetros: resource_type (frontends/backends/servers/actions/acls/healthchecks/errorfiles/resolvers/mailers), search, limit	No
opn_haproxy_get	Obtener configuración detallada de un recurso específico. Parámetros: resource_type, uuid	No
opn_haproxy_configtest	Validar la sintaxis de configuración de HAProxy antes de aplicar	No
opn_haproxy_add	Crear un nuevo recurso HAProxy. Parámetros: resource_type, config (diccionario de valores de campo)	Sí
opn_haproxy_update	Actualizar un recurso HAProxy existente (actualizaciones parciales). Parámetros: resource_type, uuid, config	Sí
opn_haproxy_delete	Eliminar un recurso HAProxy por UUID. Parámetros: resource_type, uuid	Sí
opn_reconfigure_haproxy	Aplicar cambios de configuración HAProxy pendientes	Sí

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

Servicios (11 herramientas)

Herramienta	Descripción	Escribe
opn_list_acme_certs	Certificados ACME/Let's Encrypt y su estado. Parámetros: search, limit	No
opn_list_cron_jobs	Trabajos cron programados. Parámetros: search, limit	No
opn_crowdsec_status	Estado del motor de seguridad CrowdSec y decisiones activas	No
opn_crowdsec_alerts	Alertas de seguridad CrowdSec (amenazas detectadas). Parámetros: search, limit	No
opn_list_ddns_accounts	Cuentas Dynamic DNS y su estado de actualización. Parámetros: search, limit	No
opn_add_ddns_account	Crear una nueva cuenta Dynamic DNS. Parámetros: service, hostname, username, password, checkip, interface, description	Sí
opn_reconfigure_ddclient	Aplicar cambios de configuración Dynamic DNS pendientes	Sí
opn_update_ddns_account	Actualizar una cuenta Dynamic DNS (la contraseña es de solo escritura). Parámetros: uuid, service, hostname, username, password, checkip, interface, description, enabled	Sí
opn_delete_ddns_account	Eliminar una cuenta Dynamic DNS por UUID. Parámetros: uuid	Sí
opn_mdns_repeater_status	Estado y configuración de mDNS Repeater (habilitado, interfaces, lista de bloqueo). Requiere el plugin os-mdns-repeater	No
opn_configure_mdns_repeater	Configurar mDNS Repeater para descubrimiento de dispositivos entre VLANs (HomeKit, Chromecast, AirPlay). Parámetros: enabled, interfaces	Sí

Diagnóstico (4 herramientas)

Herramienta	Descripción
opn_ping	Hacer ping a un host desde el firewall para probar conectividad. Parámetros: host, count (1-10, predeterminado 3)
opn_traceroute	Trazar la ruta de red hacia un destino. Parámetros: host, protocol (ICMP/UDP/TCP), ip_version (4/6)
opn_dns_lookup	Consulta DNS desde el firewall. Parámetros: hostname, server (servidor DNS personalizado opcional)
opn_pf_states	Consultar la tabla de estados PF activa. Parámetros: search, limit (máximo 1000)

Seguridad (1 herramienta)

Herramienta

Descripción

opn_security_audit

Auditoría de seguridad integral de 11 áreas: firmware, reglas de firewall (MVC + heredadas, agrupación de puertos, protocolos inseguros), reenvío NAT, seguridad DNS (DNSSEC, DoT), endurecimiento del sistema (SSH, HTTPS, syslog), servicios, certificados (ACME + sistema + CAs), VPN (configuración WireGuard, IPsec, OpenVPN), HAProxy (cabeceras, health checks), gateways. Hallazgos etiquetados con referencias de cumplimiento PCI DSS v4.0, BSI IT-Grundschutz, NIST 800-41, CIS.

Operaciones de Escritura y Savepoints

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

1. Antes de cualquier cambio de firewall, se crea un savepoint automáticamente
2. El cambio se aplica (activar/desactivar regla, añadir o eliminar)
3. Comienza una cuenta regresiva de 60 segundos — si no se confirma, OPNsense revierte automáticamente el cambio
4. Use opn_confirm_changes con el revision devuelto para hacer los cambios permanentes

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

OPNsense 26.7 eliminó la API de savepoint/rollback upstream, por lo que no hay reversión automática en 26.7+. El servidor no codifica un corte de versión: 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. Verifique opn_mcp_info — su campo savepoint_support informa true, false, o null si ninguna escritura ha sido sondeada aún. Las herramientas de escritura devuelven entonces un revision vacío, opn_confirm_changes responde con status: "not_applicable", y cada cambio de firewall es inmediato y permanente.

Advertencia: En OPNsense 26.7+ realice una copia de seguridad de configuración (opn_download_config, o System > Configuration > Backups) antes de habilitar escrituras, y mantenga acceso fuera de banda al equipo — una regla que lo bloquee 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 servicio y no son revertibles automáticamente.

Soporte IPv6

Totalmente Automatizado vía MCP

• Reglas de Firewall IPv6 — Crear reglas con ip_protocol="inet6" (protegido por savepoint en OPNsense < 26.7)
• Enlaces IPv6 HAProxy — Frontends con direcciones de enlace [::]:443 o [2001:db8::1]:443
• Backends IPv6 HAProxy — 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 — Overrides de host Unbound con direcciones IPv6
• Diagnóstico IPv6 — Traceroute con ip_version="6", ping vía hostname

Requiere Configuración Manual en GUI

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

• Configuración IPv6 WAN — PPPoE con delegación de prefijo DHCPv6, IPv6 estático, SLAAC
• Direccionamiento IPv6 LAN — Modo Track Interface, asignación estática /64, ID de prefijo
• Asignación de interfaces — Asignar 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 DHCPv6 de Kea es limitada en la API.
• radvd: No implementado como conjunto de herramientas separado. Dnsmasq maneja Router Advertisements de forma nativa mediante configuración de rango. Solo un daemon RA debe ejecutarse por interfaz.
• Reglas de firewall dual-stack: inet46 (dual-stack) funciona correctamente en reglas de API MVC (opn_add_firewall_rule). Sin embargo, inet46 en reglas de filtro XML heredadas (GUI) produce silenciosamente sin salida PF — este es un bug conocido de OPNsense que solo afecta reglas heredadas.
• Reglas GUI heredadas: Las reglas de firewall creadas a través de 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 Migración 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 prefijo)
3. MCP: Configurar Router Advertisements vía opn_add_dnsmasq_range con flags RA
4. MCP: Crear reglas de firewall IPv6 (ICMPv6 debe permitirse para NDP/RA/PMTUD)
5. MCP: Añadir registros DNS IPv6 vía opn_add_dns_override
6. MCP: Configurar Dynamic DNS con método checkip IPv6
7. MCP: Añadir direcciones de enlace IPv6 a frontends HAProxy
8. MCP: Verificar con opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status

Compatibilidad de Versiones

Versión OPNsense	Estado
24.7 (Thriving Tiger)	Compatible
25.1 (Ultimate Unicorn)	Compatible
25.7 (Visionary Viper)	Compatible (detecta automáticamente API snake_case)
26.1+	Compatible

El servidor detecta automáticamente la versión de OPNsense en la primera conexión y selecciona la convención de nomenclatura de endpoint API correcta (camelCase para pre-25.7, snake_case para 25.7+).

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

Solución de Problemas

Problemas de Conexión

Errores de "Connection refused" o tiempo de espera

• Verifique que OPNSENSE_URL termine con /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 API distinguen entre mayúsculas y minúsculas — cópielas exactamente del apikey.txt descargado
• Compruebe que el usuario API no esté deshabilitado en OPNsense
• Verifique que el usuario API tenga privilegios suficientes para las operaciones que intenta

403 Prohibido

• El usuario API puede carecer de permisos para el endpoint solicitado
• Para operaciones de escritura, asegúrese de que OPNSENSE_ALLOW_WRITES=true esté establecido

Problemas Específicos de Herramientas

opn_list_firewall_rules devuelve resultados vacíos

• Esta herramienta solo muestra reglas MVC/automatización, no reglas GUI heredadas
• Cree reglas vía la API de automatización o opn_add_firewall_rule para verlas

opn_ping agota el tiempo de espera

• El firewall puede no tener una ruta al host de destino
• Verifique el estado del gateway 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 seguridad. Pase include_sensitive=true para incluir contraseñas y claves (use con precaución en conversaciones de IA)

Las operaciones de escritura fallan con "writes not enabled"

• Establece OPNSENSE_ALLOW_WRITES=true en la configuración de tu servidor MCP
• Esto está deshabilitado intencionalmente por defecto por seguridad

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 un revision vacío y opn_confirm_changes devuelve status: "not_applicable". Eso es esperado, no un fallo — el cambio ya se aplicó permanentemente

Comandos de diagnóstico

Si necesitas 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

Mejores 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/video de WhatsApp a través de un firewall de denegación predeterminada usando alias de tabla de URL y reglas con alcance

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

Contribuciones

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

1. Todas las pruebas deben usar respuestas de API simuladas — nunca te conectes a un OPNsense real
2. Sin herramientas superpuestas — cada herramienta debe tener un propósito distinto
3. Escribe docstrings claros — son la única guía de la IA para la selección de herramientas
4. Devuelve datos estructurados (diccionarios), no cadenas formateadas
5. Ejecuta make validate antes de enviar

Licencia

MIT