Servidor MCP de pfSense

Administra tu firewall pfSense con lenguaje natural. 327 herramientas. 9 capas de seguridad. Un comando para empezar.

You: "Block all traffic from 203.0.113.5 on WAN"
Claude: Creates block rule → applies changes → confirms with rollback instructions

El servidor MCP de pfSense conecta Claude Desktop, Claude Code y otros clientes de IA compatibles con MCP a tu firewall pfSense. Haz preguntas, diagnostica problemas y administra tu firewall, todo a través de una conversación.

Por qué existe esto

Administrar un firewall pfSense significa hacer clic a través de pestañas de la interfaz web, recordar nombres de campos y esperar no cometer un error al escribir una regla que te bloquee el acceso. Con este servidor MCP, describes lo que quieres en inglés sencillo y la IA maneja las llamadas a la API REST, valida las entradas y te advierte antes de que ocurra algo destructivo.

Lo que lo hace diferente:

• Cada operación destructiva requiere confirmación explícita y te muestra exactamente qué sucederá

• Copia de seguridad automática de la configuración antes de cada eliminación/reinicio, con un comando de reversión de una sola línea

• La limitación de tasa (rate limiting) evita que los bucles de IA descontrolados inunden tu firewall con reglas

• La sanitización de entradas bloquea la inyección de comandos, el recorrido de rutas y XSS en cada parámetro

Related MCP server: Firewalla MCP Server

Inicio rápido

Requisitos previos: Python 3.10+, pfSense con el paquete REST API v2 instalado

git clone https://github.com/gensecaihq/pfsense-mcp-server.git
cd pfsense-mcp-server
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set PFSENSE_URL, AUTH_METHOD, and credentials

Conectar a Claude Desktop — añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "pfsense": {
      "command": "python3",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/pfsense-mcp-server",
      "env": {
        "PFSENSE_URL": "https://192.168.1.1",
        "AUTH_METHOD": "basic",
        "PFSENSE_USERNAME": "admin",
        "PFSENSE_PASSWORD": "your-password",
        "PFSENSE_VERSION": "CE_2_8_0",
        "VERIFY_SSL": "false"
      }
    }
  }
}

Empieza a hablar con tu firewall. Abre Claude Desktop y pregunta:

• "Muéstrame todo el tráfico bloqueado en la última hora"

• "¿Qué servicios están ejecutándose?"

• "Crea un reenvío de puerto para el puerto 443 al 192.168.1.50"

• "Ejecuta una comprobación completa del estado del sistema"

Qué puedes hacer

327 herramientas en todos los subsistemas principales de pfSense:

La seguridad es lo primero

La IA que gestiona un firewall de producción necesita barreras de seguridad. Este servidor tiene 9 capas:

"Delete firewall rule 5"

  1. CLASSIFY    → HIGH risk (destructive)
  2. ALLOWLIST   → tool is permitted
  3. SANITIZE    → parameters clean (no injection)
  4. RATE LIMIT  → under 10 deletes/minute
  5. DRY RUN?    → user can preview first
  6. CONFIRM     → blocked until confirm=True
  7. BACKUP      → config revision captured
  8. EXECUTE     → API call made
  9. AUDIT LOG   → action recorded with redacted params

Response includes:
  "config_backup": {
    "pre_change_revision_id": 42,
    "rollback_instruction": "restore_config_backup(revision_id=42, confirm=True)"
  }

Cada operación destructiva (52 herramientas de eliminar/reiniciar/detener) requiere confirm=True. Cada operación de creación y actualización (112 herramientas) está limitada en tasa y sanitizada. Cada parámetro sensible (contraseñas, claves, tokens) se redacta en los registros y salidas.

También puedes:

• Pasar dry_run=True para previsualizar cualquier operación destructiva sin ejecutarla

• Pasar verify_descr="Allow HTTPS" para verificar que estás eliminando la regla correcta (protege contra cambios de ID)

• Establecer MCP_READ_ONLY=true para exponer solo 118 herramientas de solo lectura (buscar, obtener, diagnosticar)

• Establecer MCP_ALLOWED_TOOLS=search_firewall_rules,get_firewall_log para restringir a herramientas específicas

Versiones de pfSense soportadas

Requiere el paquete pfSense REST API v2 de jaredhendrickson13.

Autenticación

Tres métodos soportados (configurar en .env):

Opciones de despliegue

stdio (predeterminado) — para Claude Desktop y Claude Code:

python3 -m src.main

HTTP — para acceso remoto y configuraciones multi-cliente:

python3 -m src.main -t streamable-http --port 3000

Docker — contenedor endurecido con sistema de archivos de solo lectura:

docker compose up

Seguridad del contenedor: usuario no root (mcp:1000), sistema de archivos de solo lectura, todas las capacidades eliminadas, tmpfs noexec, no-new-privileges.

Configuración

Pruebas

python3 -m pytest tests/ -v          # 308 tests
python3 -m pytest tests/ --cov=src   # with coverage

Cumplimiento de la especificación MCP

Cumple con MCP 2025-11-25 (más reciente):

• ToolAnnotations en las 327 herramientas (readOnlyHint, destructiveHint, idempotentHint)

• serverInfo.version e instructions proporcionados

• Validación de encabezado de origen (requisito MUST)

• Autenticación de token Bearer con comparación segura contra temporización

• Enlace predeterminado a localhost según la especificación SHOULD

• Transportes stdio y Streamable HTTP

Estructura del proyecto

src/
  main.py              Entry point
  server.py            FastMCP instance + API client
  client.py            pfSense REST API v2 HTTP client
  guardrails.py        9-layer defense-in-depth system
  helpers.py           Validation, parsing, safety guards
  models.py            Data models
  middleware.py        HTTP auth + Origin validation
  tools/               34 tool modules (327 tools)
tests/                 308 tests

Contribución

Necesitamos pruebas en el mundo real en diversos entornos pfSense. Consulta CONTRIBUTING o:

1. Haz un fork y crea una rama de características

2. Ejecuta python3 -m pytest tests/ -v

3. Envía un PR

Ideas: pruebas de integración contra pfSense real, soporte adicional de paquetes (Snort, Suricata), puente LLM local Ollama, gestión de múltiples instancias.

Licencia

MIT

Reconocimientos

• jaredhendrickson13 / pfrest — paquete de API REST v2 de pfSense

• JeremiahChurch — reescritura modular (PR #5)

• shawnpetersen — descubrimiento de endpoints de API v2 (PR #3)

• Netgate — pfSense

• FastMCP — framework MCP