mcp-pfsense

mcp-pfsense

Servidor MCP para gestionar firewalls pfSense a través de asistentes de IA como Claude, ChatGPT y Copilot.

Requiere: el paquete pfrest instalado en su instancia de pfSense (proporciona la API REST).

Características

19 herramientas en 7 categorías:

Categoría	Herramientas	Descripción
Sistema	get_system_status, get_interfaces	Versión, CPU, memoria, tiempo de actividad, temperatura, interfaces de red
Firewall	list_firewall_rules, add_firewall_rule, delete_firewall_rule, list_firewall_aliases	Gestión de reglas con filtrado por interfaz, listado de alias
DHCP	list_dhcp_leases, list_dhcp_static_mappings, add_dhcp_static_mapping, delete_dhcp_static_mapping	Concesiones activas, reservas de IP
DNS	list_dns_host_overrides, add_dns_host_override, delete_dns_host_override	Anulaciones de host del Resolvedor DNS Unbound
Cambios pendientes	get_pending_changes, apply_changes	Ver qué está preparado por subsistema (firewall, dhcp, dns) y aplicarlo
Monitoreo	get_gateway_status, get_arp_table, list_services	Salud de la puerta de enlace, dispositivos conectados, estado del servicio
Servicios	restart_service	Reiniciar cualquier servicio de pfSense

Seguridad

• Confirmación en dos pasos para operaciones destructivas (eliminar reglas, eliminar asignaciones, reiniciar servicios, aplicar cambios): la herramienta devuelve una advertencia en la primera llamada y solo se ejecuta cuando se llama nuevamente con confirm=true.
• Las escrituras se preparan, no se aplican en vivo. Al igual que la WebGUI de pfSense, add_* y delete_* almacenan el cambio en la configuración pero no lo activan. La respuesta de la herramienta lo indica (applied: false, más una nota de pending). Active con apply_changes(subsystem, confirm=true) — que recarga ese subsistema, incluido cualquier cambio que un humano haya dejado preparado en la WebGUI — o pase apply=true en la propia escritura cuando desee explícitamente un cambio de una sola vez. Nada de lo que haga el asistente llega al filtro de paquetes sin uno de esos dos pasos explícitos.
• delete_dhcp_static_mapping toma el interface de la asignación (su parent_id en list_dhcp_static_mappings) y mapping_id; una asignación se aborda por ambos.

Instalación

# Using uvx (recommended)
uvx mcp-pfsense

# Using pip
pip install mcp-pfsense

Requisitos previos

1. pfSense con el paquete pfrest instalado
2. Una cuenta de usuario con acceso a la API (normalmente admin)

Configuración

Establezca las variables de entorno:

Variable	Requerida	Predeterminado	Descripción
PFSENSE_HOST	Sí	—	Nombre de host o IP de pfSense
PFSENSE_PASSWORD	Sí	—	Contraseña del usuario de la API
PFSENSE_USERNAME	No	admin	Nombre de usuario de la API
PFSENSE_PORT	No	443	Puerto de la API
PFSENSE_SCHEME	No	https	http o https
PFSENSE_VERIFY_SSL	No	false	Verificar certificado SSL

Claude Desktop

Agregue a claude_desktop_config.json:

{
  "mcpServers": {
    "pfsense": {
      "command": "uvx",
      "args": ["mcp-pfsense"],
      "env": {
        "PFSENSE_HOST": "10.10.10.1",
        "PFSENSE_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add pfsense -- uvx mcp-pfsense

Luego establezca las variables de entorno en su shell o en el archivo .env.

Ejemplos de uso

Una vez conectado, pregunte a su asistente de IA:

• "¿Cuál es el estado del sistema pfSense?"
• "Muéstrame todas las reglas de firewall en la interfaz LAN"
• "Lista las concesiones DHCP activas"
• "Agrega una entrada DNS para nas.home.lan que apunte a 10.10.10.50"
• "¿Qué dispositivos están conectados a la red?" (tabla ARP)
• "Muestra la salud y latencia de la puerta de enlace"
• "Crea una regla de firewall para permitir el puerto TCP 8080 en LAN"
• "Reserva la IP 10.10.10.60 para la MAC aa:bb:cc:dd:ee:20"

Compatibilidad de la API

• pfSense: 2.7.x y 2.8.x
• pfrest: API REST v2 — cualquier versión 2.x, excepto list_dhcp_static_mappings, que requiere v2.7.0 o posterior (usa el endpoint de colección /services/dhcp_server/static_mappings agregado en esa versión).
• Python: 3.11+

El endpoint, los parámetros y la codificación que usa cada herramienta están fijados por tests/test_client_endpoints.py y tests/test_wire_format.py, derivados de las definiciones de endpoints de pfrest v2. Las versiones anteriores a 0.2.0 llamaban a varios endpoints que no existen en pfrest v2 (ver Solución de problemas).

Nota: pfrest se ejecuta en nginx (puerto 80 por defecto), separado de la WebGUI de pfSense (lighttpd en el puerto 443). Si su pfrest está configurado en un puerto no estándar, establezca PFSENSE_PORT y PFSENSE_SCHEME en consecuencia.

Solución de problemas

Solo get_system_status y get_arp_table funcionan; todo lo demás devuelve 400/404

mcp-pfsense 0.1.1 y anteriores llamaban a endpoints singulares para listar (/interface, /firewall/rule, /firewall/alias) y rutas heredadas que pfrest v2 no sirve (/status/dhcp_leases, /services/dhcpd/static_mapping, /services/unbound/host_override, /status/gateway, /status/service para GET). Actualice a 0.2.0 o posterior.

403 en list_services u otras lecturas

pfrest verifica los privilegios del usuario de la API por endpoint. Conceda al usuario los privilegios api-v2-* para los endpoints que necesite (o page-all para acceso completo) en Sistema → Administrador de usuarios.

ModuleNotFoundError: No module named 'mcp.server.fastmcp'

El SDK de Python de MCP 2.0 eliminó el módulo que mcp-pfsense 0.1.1 y anteriores importan, por lo que las instalaciones nuevas (uvx mcp-pfsense, pip install) fallaban al iniciar. Actualice a 0.2.0 o posterior, que fija mcp<2. Si debe permanecer en una versión anterior de mcp-pfsense: uvx --with "mcp<2" mcp-pfsense.

Se creó una regla / asignación / anulación pero no está en efecto

Ese es el comportamiento predeterminado: las escrituras se preparan (ver Seguridad). Verifique con get_pending_changes(subsystem) y active con apply_changes(subsystem, confirm=true), o en la WebGUI. Si una escritura devuelve 200 pero no se almacena nada, el ajuste read_only de pfrest está activado (Sistema → API REST → Configuración).

Desarrollo

git clone https://github.com/antonio-mello-ai/mcp-pfsense.git
cd mcp-pfsense
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Lint and type check
ruff check .
mypy src/

Licencia

MIT