OPNsense MCP

Haz preguntas sobre tu cortafuegos en lenguaje natural.

Cuatro herramientas de solo lectura para OPNsense: de solo lectura por defecto, y específicas sobre lo que han verificado.

Inicio rápido · Herramientas · Guía de configuración · Evidencias · Estado

Vista previa: un pequeño servidor MCP que permite a un asistente de IA inspeccionar un sistema OPNsense y — solo cuando se habilita explícitamente — crear o eliminar un tipo de alias de cortafuegos tras una confirmación, copia de seguridad y envoltorio de auditoría. Es de solo lectura por defecto. El servidor empaquetado se prueba tanto contra un objetivo HTTPS sintético como contra una VM OPNsense 26 desechable.

Pregunta en lenguaje cotidiano. El servidor indica al agente que empiece por los hechos, explique los términos de redes, haga una aclaración útil a la vez, y separe claramente las observaciones de las hipótesis.

Inicio rápido

Solo lectura, unos 15 minutos. Requiere Node.js 22.19 o superior dentro de la rama mayor 22, en macOS o Linux.

1. Guarda las credenciales de tu cortafuegos

npx -y @gabrielion/opnsense-mcp configure

Pide el origen HTTPS, una clave API y un secreto, y un archivo CA opcional. Nada se muestra en pantalla y nada se pasa como argumento de proceso. ¿Necesitas crear esa clave primero? La guía de configuración explica el lado de OPNsense con capturas de pantalla.

2. Conecta tu asistente

claude mcp add opnsense --transport stdio --env READ_ONLY=true -- npx -y @gabrielion/opnsense-mcp

[mcp_servers.opnsense]
command = "npx"
args = ["-y", "@gabrielion/opnsense-mcp"]

[mcp_servers.opnsense.env]
READ_ONLY = "true"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["npx", "-y", "@gabrielion/opnsense-mcp"],
      "environment": { "READ_ONLY": "true" }
    }
  }
}

3. Haz una pregunta

¿Cuál es el estado de mi sistema OPNsense?

¿Qué servicios se están ejecutando en mi cortafuegos?

Ejecuta /mcp primero: el servidor debería mostrar connected. Añadirlo no valida las credenciales, así que connected es la señal real.

[!TIP] ¿No tienes un cortafuegos a mano, o no estás listo para apuntar esto al tuyo? npm run test:product1b arranca una VM OPNsense desechable, crea su propia cuenta de privilegios mínimos sin ninguna credencial tuya, demuestra toda la superficie de lectura contra ella y limpia todo.

Related MCP server: OPNsense MCP Server

Qué funciona ahora

Por defecto, el servidor instalado expone cuatro herramientas de solo lectura:

• server_status comprueba el proceso MCP y su estado de solo lectura.

• opn_describe explica un recurso visible antes de que el agente lo use.

• opn_get lee el recurso singleton system.status.

• opn_list pagina los recursos de colección core.services y firewall.alias. Para los alias, lista solo las entradas de host, y el total informado cuenta esas; otros tipos de alias no se muestran.

También se registran siempre tres prompts MCP: diagnose_network_problem, publish_internal_service y block_domain_for_device. Solo producen un plan de preparación de solo lectura; no ejecutan nada.

READ_ONLY=true es el valor por defecto, y bajo él ninguna herramienta de escritura se lista ni se puede despachar.

Existen dos herramientas de escritura experimentales, opn_create y opn_delete, y operan únicamente sobre entradas de host de firewall.alias. Tres condiciones más un transporte compatible deciden si se listan en absoluto:

• READ_ONLY=false;

• ENABLED_FEATURE_FLAGS contiene experimental-alias-write;

• ALLOWED_RESOURCES nombra explícitamente firewall.alias. Una lista de permitidos ausente o vacía autoriza todas las lecturas y ninguna escritura. La lista de permitidos también filtra las lecturas, así que nombra cada ámbito que aún quieras, por ejemplo ALLOWED_RESOURCES=server.status,system.status,core.services,firewall.alias;

• el transporte es stdio o Streamable HTTP. El SSE heredado nunca los lista ni los despacha.

Una cuarta condición gobierna la llamada en lugar del listado: el cliente debe haber negociado la elicitación de formularios. Un cliente sin ella aún ve las herramientas y recibe un rechazo con CONFIRMATION_UNAVAILABLE en cada intento, antes de cualquier desafío o escritura.

Cada escritura ejecuta este envoltorio fijo, en este orden: autorización, confirmación humana que nombra el cambio, bloqueo exclusivo del objetivo, verificación previa sin efectos secundarios, intención de auditoría redactada, copia de seguridad verificada previa al cambio, re-comprobación de que el estado observado no se ha movido, la escritura, verificación del resultado, registro de auditoría final y liberación del bloqueo. Cada fallo posterior a la copia de seguridad la conserva y nunca restaura a ciegas.

Estas escrituras son experimentales por una razón. La copia de seguridad previa al cambio se escribe en un directorio temporal por proceso que se elimina cuando el servidor se apaga, por lo que no se puede consultar después. La auditoría es un anillo en memoria que conserva solo los 1024 registros más recientes (dos por escritura), sin forma persistida ni herramienta que la lea. El bloqueo es local al proceso, así que dos servidores apuntando al mismo cortafuegos no se excluyen mutuamente.

Lo que el envoltorio garantiza es limitado pero real: se rechaza una escritura a menos que se hayan registrado primero una copia de seguridad verificada y una intención de auditoría. No hay restauración ni rollback — si ocurre un fallo después de aplicar el cambio, el cambio permanece aplicado y la recuperación es manual mediante el historial de configuración propio de OPNsense. Hacer que este estado sea duradero es el siguiente hito.

Demostración local rápida

Requisitos: Node.js 22.19 o superior dentro de la rama mayor 22, npm, macOS o Linux.

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
npm ci --ignore-scripts &&
npm run test:product1a &&
npm run build

npm run test:product1a crea un tarball npm limpio, lo instala en un proyecto de consumidor aislado, lo conecta a un objetivo HTTPS sintético OPNsense de propiedad separada, llama a las tres herramientas OPNsense mediante MCP stdio sin procesar, comprueba que los secretos nunca aparecen, cierra en EOF y elimina todos los accesorios.

Conecta tu instancia de OPNsense

La forma compatible de proporcionar credenciales es el comando interactivo, que escribe el archivo privado por ti con la propiedad y los modos correctos. Desde un clon, es un subcomando del punto de entrada compilado:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
node dist/main.js configure

Instalado desde el registro, el mismo subcomando es npx -y @gabrielion/opnsense-mcp configure.

Solicita el origen HTTPS, la clave API, el secreto API y el archivo CA opcional y el nombre de servidor TLS; los secretos nunca se muestran en pantalla y nunca aparecen en un argumento de proceso. Se niega a ejecutarse en Windows y rechaza cualquier argumento.

Siempre escribe en la ruta de la plataforma e ignora OPNSENSE_CONFIG_FILE, que es una variable del lado del servidor:

• macOS: ~/Library/Application Support/opnsense-mcp/config.json;

• Linux: $XDG_CONFIG_HOME/opnsense-mcp/config.json, o si no ~/.config/opnsense-mcp/config.json.

El servidor descubre esas mismas rutas, así que la variable solo se necesita para leer un archivo guardado en otro lugar. Cada directorio que posee se crea con modo 0700 y el archivo con modo 0600; se rechazan enlaces simbólicos, propietarios ajenos y ancestros inseguros.

Dos límites prácticos: nunca sobrescribe una configuración existente, así que para rotar una clave elimina primero el archivo; y requiere una terminal real en ambos flujos, por lo que no se puede canalizar ni ejecutar en CI. Cada fallo imprime la única palabra Error a propósito — los diagnósticos son deliberadamente opacos para que nada sobre la ruta privada o las credenciales se filtre.

Alternativamente, crea tú mismo el archivo JSON fuera del repositorio y protégelo con modo 0600:

{
  "url": "https://192.0.2.1",
  "apiKey": "your-dedicated-read-only-api-key",
  "apiSecret": "your-api-secret",
  "caFile": "/absolute/path/to/your-ca.pem",
  "tlsServerName": "firewall.example.internal"
}

El archivo debe ser un archivo regular, sin enlace simbólico, propiedad del usuario actual, en una ruta absoluta, con exactamente modo 0600, exactamente un enlace duro y como máximo 16 KiB. 0400 también se rechaza. url debe ser un origen HTTPS exacto. caFile es opcional cuando el certificado del cortafuegos ya encadena con una CA de confianza. tlsServerName es opcional cuando la URL usa una dirección IP pero el certificado verificado usa un nombre DNS. La verificación TLS siempre permanece habilitada. Usa una clave OPNsense dedicada de privilegios mínimos; no pegues credenciales en el chat ni en argumentos de comando.

Transportes. stdio es el predeterminado y el único transporte ejercitado de extremo a extremo por las pruebas empaquetadas; dist/main.js siempre inicia stdio. Existe un transporte Streamable HTTP como punto de entrada separado (npm run start:http) detrás de MCP_HTTP_ENABLED, vinculado a loopback con una lista de permitidos Host/Origin y un MCP_HTTP_TOKEN bearer de al menos 32 caracteres; no está cubierto por una prueba de humo de cliente, así que no se hace ninguna afirmación de compatibilidad con clientes para él. Existe una superficie de compatibilidad SSE heredada detrás de MCP_LEGACY_SSE_ENABLED, que además requiere MCP_HTTP_ENABLED=true — configurarla sola es un error de inicio — y nunca expone las herramientas de escritura con confirmación.

Para ejecutar directamente el servidor stdio limpio de protocolo:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
OPNSENSE_CONFIG_FILE="/absolute/path/to/opnsense.json" READ_ONLY=true node dist/main.js

Nunca apuntes desarrollo o pruebas a un cortafuegos de producción. Usa la prueba de VM desechable a continuación para trabajo en vivo.

Prueba OPNsense 26 desechable

En macOS o Linux, instala QEMU más Node.js 22, y luego ejecuta:

npm run vm:doctor
npm run test:product1b

vm:doctor informa de cada dependencia de host faltante sin modificar la máquina. test:product1b es dueño de toda la prueba en vivo: verifica y almacena en caché la imagen nano oficial fijada de OPNsense 26.7, inicia una VM local, crea un usuario API desechable de privilegios mínimos a través de la consola serie sin ninguna credencial de operador, empaqueta e instala este paquete npm, llama a server_status, opn_describe system.status, opn_get system.status y opn_list core.services a través de una sesión MCP, luego detiene la VM y elimina el overlay, las credenciales API, el certificado y el paquete temporal. La primera ejecución descarga un archivo de aproximadamente 557 MB y crea una imagen base de solo lectura de 3 GiB en la caché del usuario.

La evidencia histórica de Product 1B sigue siendo la prueba de solo dos llamadas remotas: GET /api/core/system/status y POST /api/core/service/search. Su evidencia legible por máquina saneada también registra su host exacto, QEMU, firmware, transporte y comprobaciones de limpieza sin retener datos del cortafuegos ni credenciales.

La implementación de escritura de alias apunta a GET /api/core/backup/download/this para la copia de seguridad previa al cambio, luego POST /api/firewall/alias/searchItem, addItem o delItem/{uuid}, y luego la aplicación reconfigure. Esos detalles de endpoints tienen cobertura determinista de objetivo sintético. Product 3 demuestra en una VM desechable solo lo siguiente: la superficie de escritura y este ciclo de vida exacto de firewall.alias: ausente, crear, presente, eliminar, ausente, seguido de limpieza de VM y una comprobación sin residuos. La atestación de VM Product 3 vinculada a commit registra el commit y árbol probados, la imagen de firmware fijada, las entradas de política y las comprobaciones de ciclo de vida fijas sin retener datos del cortafuegos ni credenciales. La atestación de Product 3 no demuestra uso en producción, estado duradero, copias de seguridad duraderas, una pista de auditoría duradera, restauración o rollback automático.

El recorrido de restauración además revierte esa misma mutación de alias directamente a través de la consola de la VM desechable — no a través de la API — y luego re-observa la API para comprobar que la mutación ha desaparecido. La atestación de VM Product 3 de recorrido de restauración registra el commit y árbol probados, la misma imagen de firmware fijada y entradas de política, las comprobaciones del ciclo de vida del alias y las comprobaciones de copia de seguridad restaurada y estado revertido, de nuevo sin retener datos del cortafuegos ni credenciales, producida con node scripts/vm/product3-restore.mjs --attestation-out "$PWD/docs/evidence/product3-restore-vm.json".

Privilegios de cuenta desechable. Las cuentas se crean exactamente con estas ACL estándar, y nada más. Ambos perfiles de ACL tienen ahora evidencia en vivo solo en sus escenarios exactos: el perfil de solo lectura en Producto 1B y el perfil de escritura de alias en Producto 3.

• cuenta de solo lectura: page-system-status, page-status-services, user-config-readonly;

• cuenta de escritura de alias: page-system-status, page-status-services, page-diagnostics-configurationhistory, page-firewall-alias-edit.

user-config-readonly está deliberadamente ausente de la cuenta de escritura de alias: observamos que hace que el controlador de modelo mutable de OPNsense rechace los guardados de alias. page-diagnostics-configurationhistory se concede para la solicitud de copia de seguridad de configuración previa al cambio. Ambas afirmaciones provienen de nuestra propia experiencia de arranque, no de un mapeo ascendente citado.

OpenCode

Añade un opencode.json a nivel de proyecto (reemplaza ambas rutas absolutas):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["node", "/absolute/path/to/OPNSenseMCP/dist/main.js"],
      "environment": {
        "READ_ONLY": "true",
        "OPNSENSE_CONFIG_FILE": "/absolute/path/to/opnsense.json"
      }
    }
  }
}

Luego ejecuta opencode mcp list; opnsense debería estar conectado. La evidencia de humo confirmada cubre solo OpenCode 1.18.16 con opencode/deepseek-v4-flash-free contra el tarball instalado y el objetivo HTTPS sintético. Registra resúmenes de herramienta/resultado, no datos de firewall ni credenciales. Consulta la evidencia legible por máquina.

Otros clientes MCP pueden lanzar el mismo comando stdio, pero no se hace ninguna afirmación de soporte específico del cliente hasta que su propia prueba de humo versionada pase.

Cómo se prueba esta vista previa

• TypeScript estricto, formato, lint, encabezados de licencia y pruebas unitarias/de integración deterministas.

• npm pack/install limpio más TLS, autenticación Basic, validación de respuesta, redacción de secretos, apagado y limpieza contra un objetivo sintético.

• npm pack/install limpio histórico contra una VM desechable de OPNsense 26.1.6 para las dos llamadas remotas del Producto 1B, incluyendo propiedad de la VM, integridad de imagen fijada, credenciales aisladas, fijación TLS y limpieza inversa.

• Una ejecución del Producto 3 vinculada a un commit contra una VM desechable de OPNsense 26.7 para la superficie escribible y el ciclo de vida exacto del alias de host: ausente, crear, presente, eliminar, ausente, seguido de limpieza de la VM y una verificación sin residuos.

• Una instalación hermética del paquete para la prueba del objetivo sintético y ambos ejecutores de VM: el consumidor resuelve cada dependencia desde un registro npm solo de loopback derivado del bloqueo, con caché vacía y proxies inalcanzables, por lo que no hay acceso a Internet involucrado y ningún lanzamiento ascendente puede cambiar lo que se instala.

• Comprobaciones de interoperabilidad MCP específicas para las versiones de protocolo 2025-11-25 y el borrador 2026-07-28.

• Una prueba de humo de enrutamiento real de OpenCode 1.18.16 usando opencode/deepseek-v4-flash-free.

El estado completo de desarrollo y la transferencia de máquina a máquina se registran en docs/project-status.md. La evaluación canónica planificada del agente se especifica en el diseño de evaluación DeepEval y OPNsense: evaluará el uso de herramientas MCP de Claude Code y la respuesta final mientras requiere por separado una lectura MCP determinista del estado de la VM desechable. Esas pruebas y cualquier puntuación de referencia aún no están implementadas ni reclamadas.

Juntos, estos controles cubren el paquete, la ruta de lectura sintética, las dos llamadas remotas históricas del Producto 1B declaradas, y no más que el ciclo de vida acotado mencionado anteriormente. No prueban:

• exposición de DNS público, ACME o HAProxy en Internet;

• comportamiento contra un firewall de producción;

• copias de seguridad duraderas o un rastro de auditoría duradero: ambos existen, pero solo durante la vida del proceso;

• restauración, o cualquier reversión automática de un cambio aplicado;

• escrituras a cualquier cosa que no sean entradas de host de firewall.alias;

• ninguna garantía más allá de los primeros 100 alias de host: el resumen del estado previo al cambio y la lectura posterior leen una sola página de 100, por lo que más allá de eso un crear puede informar un resultado no verificado y un eliminar solo puede probar que la entrada no estaba en la página que leyó;

• instalación nativa de Windows u operación del cliente;

• un benchmark agéntico completo o una puntuación de benchmark.

El despacho de API crudo, shell/SSH de forma libre, IaC masivo, un panel de control y una paridad heredada amplia están ausentes.

Hoja de ruta del producto y solicitudes de ejemplo

El sobre de seguridad de mutación — autorización con ámbito, confirmación humana, copia de seguridad verificada, auditoría redactada, verificación de resultados, limpieza con cierre ante fallos — está implementado y probado contra un objetivo HTTPS sintético. El próximo hito es hacer que su estado sea duradero: una raíz de estado persistente, un bloqueo entre procesos, una auditoría de solo anexión y un comando local reconcile, para que las garantías sobrevivan a un reinicio. Solo entonces se puede reconsiderar la etiqueta experimental en las escrituras de alias.

Los flujos de trabajo guiados posteriores son deliberadamente objetivos a nivel de usuario, por ejemplo:

• "Mi portátil pierde Internet todas las tardes. ¿Puedes investigar y explicar lo que encuentres?"

• "Bloquea TikTok solo para la tableta de mi hijo, sin afectar a los otros dispositivos."

• "Publica este servicio internamente con un nombre DNS amigable, un certificado interno y un proxy inverso."

Esos tres flujos de trabajo son ejemplos de hoja de ruta, no afirmaciones del Producto 1A. La publicación orientada a Internet con DNS público, Let's Encrypt y HAProxy es un hito de laboratorio a más largo plazo después de escrituras seguras y cobertura de VM privada.

Estado de distribución: publicado en npm como @gabrielion/opnsense-mcp, por lo que npx -y @gabrielion/opnsense-mcp ejecuta el servidor publicado; una instalación desde URL de git aún construye su propio dist/ a través del script prepare. Las pruebas empaquetadas instalan un tarball construido localmente servido por un registro de loopback derivado del bloqueo de cualquier manera, por lo que lo que ejercitan es este árbol en lugar de cualquier copia del registro. Aún no se ofrece ninguna garantía de versionado o actualización.

Estado de plataforma: macOS y Linux son los hosts de desarrollo actualmente verificados. Windows nativo sigue siendo un objetivo de producto requerido, pero el soporte de paquete y cliente no se reivindica hasta que pase la compuerta posterior windows-2025.

Licencia y marca comercial

Licenciado bajo AGPL-3.0-o-posterior; ver LICENSE. La AGPL permite uso comercial mientras requiere disponibilidad del código fuente cubierto, incluido para uso en red. OPNsense es una marca comercial de Deciso B.V. Este proyecto independiente no está afiliado, patrocinado ni respaldado por Deciso B.V. ni por el proyecto OPNsense.