OPNsense MCP Server

Un servidor MCP completo para gestionar firewalls OPNsense, que ofrece más de 300 herramientas para configuración y monitoreo.

GitHub

Prueba este MCPPatrocinado

Documentación

OPNsense MCP Server

Un servidor modular del Protocolo de Contexto de Modelo (MCP) que proporciona 88 herramientas basadas en módulos que dan acceso a más de 2000 métodos de gestión del cortafuegos OPNsense a través de una interfaz TypeScript con seguridad de tipos.

Características

Arquitectura modular - 88 herramientas lógicas (una por módulo) en lugar de más de 2000 herramientas individuales
Cobertura completa de la API - Acceso a 752 métodos principales y 1271 métodos de complementos
Seguridad de tipos - Soporte completo de TypeScript con @richard-stovall/opnsense-typescript-client v0.5.3
Soporte de complementos - Soporte opcional para 64 módulos de complementos
Organización inteligente - Operaciones relacionadas agrupadas por módulo para facilitar su descubrimiento

El servidor MCP actúa como un puente entre los asistentes de IA (como Claude Desktop) y su cortafuegos OPNsense, proporcionando acceso seguro a la API a través de una interfaz de herramientas modular.

Usage in Claude Desktop OPNsense MCP Server Network Architecture

Usage in Claude Code

Instalación

Como servidor MCP

Este paquete está diseñado para usarse como servidor MCP (Protocolo de Contexto de Modelo) con asistentes de IA como Claude Desktop, Cursor u otros clientes compatibles con MCP.

Requisitos previos

Node.js 18 o superior
Un cortafuegos OPNsense con acceso a la API habilitado
Clave y secreto de API de su instalación de OPNsense

Instalar desde npm

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

Uso como servidor MCP

Configuración de Claude Desktop

Agregue lo siguiente a su archivo de configuración de 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 de configuración alternativos

Usando argumentos de línea de comandos:

{
  "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 herramientas de complementos: Para incluir las 64 herramientas de módulos de complementos, agregue "--plugins" a los argumentos o establezca "INCLUDE_PLUGINS": "true" en env.

Probando la configuración

Una vez configurado, puede probar la conexión preguntando a Claude:

"¿Qué herramientas MCP están disponibles?"
"Usa core_manage para obtener el estado del sistema"
"Usa firewall_manage para buscar todos los alias"
"Usa interfaces_manage para listar todas las interfaces de red"

Solución de problemas de configuración de Claude Desktop

Problemas de conexión:

Verifique que su API de OPNsense esté habilitada
Compruebe que la clave de API tenga los permisos adecuados
Asegúrese de que la IP/nombre de host sea accesible desde su máquina
Para certificados autofirmados, use --no-verify-ssl o establezca "OPNSENSE_VERIFY_SSL": "false"

Ver registros del servidor: Revise los registros de Claude Desktop para ver cualquier mensaje de error del servidor MCP.

Probar manualmente: Puede probar el servidor manualmente antes de usarlo con 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

Esto debería mostrar:

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

Configuración de Cursor

Agregue a su configuración de Cursor (.cursor/mcp.json en su proyecto o ~/.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"
      }
    }
  }
}

Opciones de configuración

El servidor acepta configuración a través de variables de entorno:

OPNSENSE_URL - URL del host de OPNsense (obligatorio)
OPNSENSE_API_KEY - Clave de API para autenticación (obligatorio)
OPNSENSE_API_SECRET - Secreto de API para autenticación (obligatorio)
INCLUDE_PLUGINS - Establecer en "true" para habilitar las 64 herramientas de módulos de complementos (opcional)
OPNSENSE_VERIFY_SSL - Establecer en "false" para deshabilitar la verificación SSL (solo desarrollo)

Cómo funciona

El servidor MCP modular proporciona a su asistente de IA 88 herramientas basadas en módulos. Cada herramienta representa un módulo de OPNsense y acepta un parámetro method para especificar la operación.

Patrón de uso de herramientas:

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

Ejemplos de indicaciones:

"Usa core_manage para verificar el estado del sistema"
"Usa firewall_manage para listar todos los alias del cortafuegos"
"Usa interfaces_manage para obtener información de las interfaces de red"
"Usa plugin_nginx_manage para verificar la configuración del servidor web"
"Usa diagnostics_manage para ver la tabla ARP"

El enfoque modular facilita el descubrimiento de funcionalidades relacionadas: todas las operaciones del cortafuegos están en firewall_manage, todas las operaciones de VPN en sus respectivos módulos (openvpn_manage, ipsec_manage, wireguard_manage).

Herramientas de módulos disponibles

Módulos principales (24 herramientas)

Cada herramienta proporciona acceso a todos los métodos dentro de ese módulo:

Nombre de la herramienta	Descripción	Métodos de ejemplo
`core_manage`	Funciones principales del sistema	`backupBackups`, `systemReboot`, `firmwareInfo`
`firewall_manage`	Reglas y alias del cortafuegos	`aliasSearchItem`, `filterAddRule`, `natSearchRule`
`interfaces_manage`	Interfaces de red	`getInterfaces`, `vlanAddItem`, `setInterface`
`diagnostics_manage`	Diagnóstico del sistema	`interfaceGetArp`, `systemActivityGetActivity`
`auth_manage`	Autenticación	`userSearchUser`, `groupSearchGroup`
`firmware_manage`	Actualizaciones 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 complementos (64 herramientas cuando están habilitados)

Módulos de complementos populares:

Nombre de la herramienta	Descripción	Métodos de ejemplo
`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`

Compilar desde el código fuente

Si desea contribuir o personalizar el 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

Desarrollo

Scripts de desarrollo

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

Pila tecnológica

Runtime: Node.js con tsx para ejecución de TypeScript
Gestor de paquetes: Yarn 4.9.2 con Plug'n'Play
Sistema de compilación: Compilación simple de TypeScript a un solo archivo
Lenguaje: TypeScript 5.3+
SDK de MCP: @modelcontextprotocol/sdk
Cliente de API: @richard-stovall/opnsense-typescript-client
Validación: Zod para validación de esquemas
Pruebas: Jest con soporte de TypeScript

Integración de API

El servidor utiliza el paquete @richard-stovall/opnsense-typescript-client que proporciona:

Seguridad de tipos completa para todas las llamadas a la API
Manejo de errores y reintentos integrados
Soporte para los 601 endpoints de la API de OPNsense
Implementación basada en la API Fetch moderna

Ejemplo de implementación de herramienta

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

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar una solicitud de extracción (Pull Request).

Haga un fork del repositorio
Cree su rama de características (git checkout -b feature/AmazingFeature)
Realice sus cambios (git commit -m 'Add some AmazingFeature')
Envíe los cambios a la rama (git push origin feature/AmazingFeature)
Abra una solicitud de extracción

Licencia

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

Agradecimientos

Construido sobre el Protocolo de Contexto de Modelo de Anthropic
Impulsado por @richard-stovall/opnsense-typescript-client
Inspirado por la comunidad de OPNsense

Hecho con amor para la comunidad de OPNsense