pfsense-mcp

A bidirectional AI agent for pfSense. Two components, one package: an MCP server for Claude Code control, and an emergency brain that activates when your network needs help.

Status: Planning Author: Claude (claude@arktechnwa.com) + Meldrey License: MIT Organization: ArktechNWA

Why?

Your AI assistant can help configure firewalls, but it's blind to your network's health. It can't see if your WAN is down, can't check DHCP leases, can't restart a stuck interface.

Worse: when your network breaks, you lose access to your AI assistant entirely.

pfclaude solves both problems:

1. Normal mode: Claude Code controls pfSense via MCP — full visibility, full capability
2. Emergency mode: When Claude Code is unreachable, pfSense's onboard brain activates — diagnostics, notifications, autonomous recovery

Philosophy

1. Maximum capability — Expose everything pfSense can do
2. User controls exposure — Checkbox permissions, not hardcoded limits
3. Maximum availability — Multiple transport channels, graceful fallbacks
4. Lightweight emergency brain — Minimal resource usage, adaptive monitoring
5. Bidirectional communication — Email commands work even when network is broken

Architecture

┌─────────────────────────────────────────────────────────────────┐
│ Claude Code (workstation)                                       │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pfsense-mcp                                                 │ │
│ │  - Full pfSense API passthrough                             │ │
│ │  - All operations: firewall, NAT, DHCP, VPN, logs, etc.     │ │
│ │  - Authenticated over HTTPS                                 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
           ↕ HTTPS + API Key (primary)
           ↕ SSH (fallback)
┌─────────────────────────────────────────────────────────────────┐
│ pfSense Router                                                  │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ pfClaude Package                                            │ │
│ │                                                             │ │
│ │  NORMAL MODE          │  EMERGENCY MODE                     │ │
│ │  ─────────────        │  ──────────────                     │ │
│ │  API Server           │  Watchdog Daemon                    │ │
│ │  ↕ MCP talks here     │  ↳ Health monitors                  │ │
│ │                       │  ↳ Trigger detection                │ │
│ │  Full pfSense ops     │  ↳ Decision engine                  │ │
│ │  Auth'd requests      │  ↳ Autonomous actions               │ │
│ │                       │  ↳ Notification dispatch            │ │
│ │                       │                                     │ │
│ │  ───────────────────────────────────────────────────────── │ │
│ │  SHARED INFRASTRUCTURE                                      │ │
│ │  • Permission matrix (checkboxes)                           │ │
│ │  • SMTP client (outbound alerts)                            │ │
│ │  • Email parser (inbound commands)                          │ │
│ │  • Cloud beacon (optional status sync)                      │ │
│ │  • Local knowledge base (patterns, history)                 │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Authentication

API Authentication

Simple, proven security:

{
  "auth": {
    "api_key": "randomly-generated-64-char-key",
    "require_https": true,
    "ip_whitelist": ["192.168.1.0/24", "10.0.0.5"],
    "rate_limit": 100,
    "lockout_threshold": 5,
    "lockout_duration": 900
  }
}

• API key transmitted in header: X-PfClaude-Key: <key>
• HTTPS required (uses pfSense's existing certificate)
• Optional IP whitelist (only accept from known Claude IPs)
• Rate limiting: 100 requests/min default
• Failed auth lockout: 5 failures → 15 min ban

Email Authentication

For inbound email commands:

Subject: [PFCLAUDE:1234] status

• Sender must be in whitelist
• PIN must match configured value
• Timestamp validation (reject if >5min old)
• Rate limit: 10 commands/hour

Trigger Conditions

Tiered detection with configurable thresholds:

Tier 1: Monitoring (always on, ultra-light)

Tier 2: Concern (triggers increased monitoring)

Tier 3: Emergency (activates autonomous response)

Health Check Design

Lightweight, adaptive, CPU-aware:

┌─────────────────────────────────────────────────────────────────┐
│ ADAPTIVE FREQUENCY                                              │
│                                                                 │
│ State: HEALTHY     → Check every 60s                            │
│ State: CONCERNED   → Check every 15s                            │
│ State: DEGRADED    → Check every 5s                             │
│ State: EMERGENCY   → Check every 2s (active response mode)      │
│                                                                 │
│ CPU AWARENESS                                                   │
│ • If system load > 80%, halve check frequency                   │
│ • If memory < 10% free, disable non-critical checks             │
│ • Never consume > 2% CPU for monitoring                         │
│                                                                 │
│ HYSTERESIS                                                      │
│ • Each check returns: OK (0), WARN (1), FAIL (2)                │
│ • Aggregate score determines state transition                   │
│ • Need 3 consecutive same-state readings to transition          │
└─────────────────────────────────────────────────────────────────┘

Autonomous Actions

User configures what pfClaude can do WITHOUT asking:

Always Safe (default: enabled)

Diagnostic (default: enabled)

Restorative (default: disabled)

Failover (default: disabled)

Defensive (default: disabled)

Local Intelligence

Pattern Memory

{
  "pattern_memory": {
    "enabled": true,
    "database": "/var/db/pfclaude/patterns.db",
    "max_size_mb": 10,
    "retention_days": 90
  }
}

• Stores: "Last time X happened, Y was the cause"
• Learns: "Interface restart fixed this 3/4 times"
• Tracks: Normal baselines (traffic, latency, errors)
• SQLite DB, <10MB footprint

Haiku Batch Analysis (optional)

{
  "haiku_analysis": {
    "enabled": true,
    "schedule": "0 3 * * *",
    "api_key_env": "PFCLAUDE_ANTHROPIC_KEY",
    "sanitize": ["ip", "mac", "hostname"],
    "max_log_lines": 1000
  }
}

• Nightly batch: Send sanitized logs to Anthropic
• Haiku analyzes patterns, anomalies, recommendations
• Results stored locally as "learned insights"
• Cost: ~$0.01/day for typical home network

Notification Channels

User configures their own escalation paths:

{
  "notifications": {
    "email": {
      "enabled": true,
      "smtp_server": "smtp.gmail.com",
      "smtp_port": 587,
      "username_env": "SMTP_USER",
      "password_env": "SMTP_PASS",
      "recipients": ["you@example.com"]
    },
    "pushover": {
      "enabled": false,
      "api_key_env": "PUSHOVER_KEY",
      "user_key_env": "PUSHOVER_USER"
    },
    "webhook": {
      "enabled": false,
      "url": "https://your-service.com/webhook",
      "headers": {"Authorization": "Bearer xxx"}
    },
    "telegram": {
      "enabled": false,
      "bot_token_env": "TELEGRAM_TOKEN",
      "chat_id": "123456789"
    },
    "cloud_beacon": {
      "enabled": false,
      "url": "https://your-beacon.com/status",
      "shared_secret_env": "BEACON_SECRET"
    }
  }
}

Escalation Levels

Email Commands

When WAN works but LAN doesn't, email becomes the control channel:

Command Format

To: pfclaude@your-pfsense.com
Subject: [PFCLAUDE:1234] status
Body: (optional context)

Available Commands

Example Response

Subject: Re: [PFCLAUDE:1234] status

pfClaude Status Report
Generated: 2025-12-29 15:42:00 UTC

SYSTEM: DEGRADED (score: 4/10)

Interfaces:
  WAN  (igb0): UP - 98.2.1.45 - 12ms latency
  LAN  (igb1): UP - 192.168.1.1 - NO TRAFFIC 5min  ← Problem
  OPT1 (igb2): DOWN - disabled

Recent Events:
  15:37 - LAN traffic dropped to zero
  15:38 - DHCP requests stopped
  15:40 - Watchdog entered CONCERNED state

Recommended: Check switch connectivity to LAN port

Cloud Beacon (optional)

For checking router status from anywhere:

{
  "cloud_beacon": {
    "enabled": true,
    "url": "https://your-beacon-server.com/api/beacon",
    "router_id": "home-pfsense",
    "shared_secret_env": "BEACON_SECRET",
    "frequency_healthy": 60,
    "frequency_degraded": 15
  }
}

Self-Hosted Option

Docker image provided for running your own beacon receiver:

docker run -d -p 8080:8080 \
  -e BEACON_SECRET=your-secret \
  arktechnwa/pfclaude-beacon

Features:

• Receives status beacons from pfSense
• Stores recent logs (configurable retention)
• Web dashboard for status checks
• Can relay commands back to pfSense

Beacon Protocol

POST /beacon
{
  "router_id": "home-pfsense",
  "timestamp": "2025-12-29T15:42:00Z",
  "state": "healthy",
  "score": 9,
  "interfaces": {
    "wan": {"status": "up", "ip": "98.2.1.45", "latency_ms": 12},
    "lan": {"status": "up", "ip": "192.168.1.1", "clients": 15}
  },
  "recent_events": [],
  "hmac": "..."
}

Payload: <2KB, designed for minimal bandwidth.

MCP Tools

EVERYTHING pfSense can do, exposed via MCP:

System

Interfaces

Firewall

NAT

DHCP

DNS

VPN

Routing

Traffic

Logs

Packages

Services

Diagnostics

Permission Matrix

Granular control via pfSense WebGUI:

Permission Levels

WebGUI Configuration

┌─────────────────────────────────────────────────────────────────┐
│ pfClaude > Settings > Permissions                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ MCP API Permissions                                             │
│ ─────────────────────────────────────────────────────────────── │
│                                                                 │
│ READ OPERATIONS                          [Select All] [Clear]   │
│ ☑ System info & status                                         │
│ ☑ Interface status & stats                                     │
│ ☑ Firewall rules (view)                                        │
│ ☑ DHCP leases                                                  │
│ ☑ Logs (all)                                                   │
│ ☑ Diagnostics (ping, traceroute, etc)                          │
│                                                                 │
│ SERVICE CONTROL                          [Select All] [Clear]   │
│ ☐ Restart interfaces                                           │
│ ☐ Restart services (DHCP, DNS, etc)                            │
│ ☐ Flush state table                                            │
│ ☐ Clear caches                                                 │
│                                                                 │
│ CONFIGURATION CHANGES                    [Select All] [Clear]   │
│ ☐ Modify firewall rules                                        │
│ ☐ Modify NAT rules                                             │
│ ☐ Modify DHCP settings                                         │
│ ☐ Add/remove static routes                                     │
│                                                                 │
│ DANGEROUS OPERATIONS                     [Select All] [Clear]   │
│ ☐ System reboot                                                │
│ ☐ System shutdown                                              │
│ ☐ Install/remove packages                                      │
│ ☐ Gateway failover                                             │
│                                                                 │
│ ─────────────────────────────────────────────────────────────── │
│ ☐ BYPASS ALL PERMISSIONS (danger mode)                         │
│                                                                 │
│                                    [Save] [Reset to Defaults]   │
└─────────────────────────────────────────────────────────────────┘

Storage & Hygiene

{
  "storage": {
    "email_queue": {
      "max_messages": 100,
      "max_age_days": 10,
      "cleanup_schedule": "0 4 * * *"
    },
    "logs": {
      "pfclaude_events_days": 7,
      "diagnostic_snapshots_days": 3
    },
    "pattern_memory": {
      "persistent": true,
      "compact_schedule": "0 5 * * 0"
    },
    "total_footprint_mb": 50
  }
}

Installation

pfSense Package

System > Package Manager > Available Packages > pfClaude

Or manual:

pkg add https://github.com/ArktechNWA/pfsense-mcp/releases/latest/pfsense.pkg

MCP Server (Claude Code side)

npm install -g @arktechnwa/pfsense-mcp

Claude Code Integration

{
  "mcpServers": {
    "pfsense": {
      "command": "pfsense-mcp",
      "env": {
        "PFSENSE_HOST": "192.168.1.1",
        "PFSENSE_API_KEY": "your-api-key"
      }
    }
  }
}

Requirements

pfSense Side

• pfSense 2.7+ or pfSense Plus 23.09+
• 50MB free storage
• Network connectivity (obviously)

Claude Code Side

• Node.js 18+
• Network access to pfSense

Optional

• Anthropic API key (for Haiku batch analysis)
• SMTP server (for email notifications)
• Self-hosted beacon server (for cloud status)

Security Considerations

1. API key authentication — No unauthenticated access
2. HTTPS required — Encrypted transport
3. IP whitelist — Restrict to known Claude IPs
4. Rate limiting — Prevent brute force
5. Email PIN — Authenticate inbound commands
6. Permission matrix — User controls exposure
7. Audit logging — All actions logged
8. No default dangerous permissions — User must enable

Credits

Created by Claude (claude@arktechnwa.com) in collaboration with Meldrey. Part of the ArktechNWA MCP Toolshed.

Built because your firewall should be able to call for help when it needs it.