pfSense MCP-Server

Verwalten Sie Ihre pfSense-Firewall mit natürlicher Sprache. 327 Tools. 9 Sicherheitsebenen. Ein Befehl zum Starten.

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

Der pfSense MCP-Server verbindet Claude Desktop, Claude Code und andere MCP-kompatible KI-Clients mit Ihrer pfSense-Firewall. Stellen Sie Fragen, diagnostizieren Sie Probleme und verwalten Sie Ihre Firewall – alles durch Konversation.

Warum gibt es dieses Projekt?

Die Verwaltung einer pfSense-Firewall bedeutet normalerweise, sich durch Web-UI-Tabs zu klicken, sich Feldnamen zu merken und zu hoffen, dass man nicht versehentlich eine Regel ändert, die einen aussperrt. Mit diesem MCP-Server beschreiben Sie Ihr Anliegen in einfachem Englisch, und die KI übernimmt die REST-API-Aufrufe, validiert Eingaben und warnt Sie, bevor etwas Destruktives geschieht.

Was es besonders macht:

• Jeder destruktive Vorgang erfordert eine explizite Bestätigung und zeigt Ihnen genau, was passieren wird.

• Automatisches Konfigurations-Backup vor jedem Löschvorgang/Neustart – mit einem einzeiligen Rollback-Befehl.

• Ratenbegrenzung verhindert, dass KI-Schleifen Ihre Firewall mit Regeln überfluten.

• Eingabesanitisierung blockiert Befehlsinjektionen, Pfad-Traversal und XSS in jedem Parameter.

Related MCP server: Firewalla MCP Server

Schnellstart

Voraussetzungen: Python 3.10+, pfSense mit installiertem REST API v2 Paket

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

Verbindung zu Claude Desktop herstellen – fügen Sie dies zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu:

{
  "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"
      }
    }
  }
}

Fangen Sie an, mit Ihrer Firewall zu sprechen. Öffnen Sie Claude Desktop und fragen Sie:

• "Zeige mir den gesamten blockierten Datenverkehr der letzten Stunde"

• "Welche Dienste laufen gerade?"

• "Erstelle eine Portweiterleitung für Port 443 auf 192.168.1.50"

• "Führe einen vollständigen System-Gesundheitscheck durch"

Was Sie tun können

327 Tools für jedes wichtige pfSense-Subsystem:

Sicherheit zuerst

Eine KI, die eine Produktions-Firewall verwaltet, benötigt Schutzmechanismen. Dieser Server verfügt über 9 Ebenen:

"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)"
  }

Jeder destruktive Vorgang (52 Lösch-/Neustart-/Halt-Tools) erfordert confirm=True. Jeder Erstellungs- und Aktualisierungsvorgang (112 Tools) ist ratenbegrenzt und bereinigt. Jeder sensible Parameter (Passwörter, Schlüssel, Token) wird in Protokollen und Ausgaben geschwärzt.

Sie können außerdem:

• dry_run=True übergeben, um jeden destruktiven Vorgang vorab zu prüfen, ohne ihn auszuführen.

• verify_descr="Allow HTTPS" übergeben, um sicherzustellen, dass Sie die richtige Regel löschen (schützt vor ID-Verschiebungen).

• MCP_READ_ONLY=true setzen, um nur die 118 schreibgeschützten Tools (Suche, Abruf, Diagnose) freizugeben.

• MCP_ALLOWED_TOOLS=search_firewall_rules,get_firewall_log setzen, um den Zugriff auf bestimmte Tools zu beschränken.

Unterstützte pfSense-Versionen

Erfordert das pfSense REST API v2 Paket von jaredhendrickson13.

Authentifizierung

Drei Methoden werden unterstützt (Konfiguration in .env):

Bereitstellungsoptionen

stdio (Standard) – für Claude Desktop und Claude Code:

python3 -m src.main

HTTP – für Fernzugriff und Multi-Client-Setups:

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

Docker – gehärteter Container mit schreibgeschütztem Dateisystem:

docker compose up

Container-Sicherheit: Nicht-Root-Benutzer (mcp:1000), schreibgeschütztes Dateisystem, alle Capabilities entfernt, noexec tmpfs, no-new-privileges.

Konfiguration

Testen

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

Einhaltung der MCP-Spezifikation

Konform mit MCP 2025-11-25 (aktuell):

• ToolAnnotations für alle 327 Tools (readOnlyHint, destructiveHint, idempotentHint)

• serverInfo.version und instructions bereitgestellt

• Validierung des Origin-Headers (MUSS-Anforderung)

• Bearer-Token-Authentifizierung mit zeitlich sicherem Vergleich

• Standard-Bindung an localhost gemäß Spezifikation (SHOULD)

• stdio- und Streamable-HTTP-Transporte

Projektstruktur

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

Mitwirken

Wir benötigen Tests in realen, vielfältigen pfSense-Umgebungen. Siehe CONTRIBUTING oder:

1. Forken Sie das Projekt und erstellen Sie einen Feature-Branch

2. Führen Sie python3 -m pytest tests/ -v aus

3. Reichen Sie einen PR ein

Ideen: Integrationstests gegen echte pfSense-Instanzen, zusätzliche Paketunterstützung (Snort, Suricata), Ollama lokale LLM-Brücke, Multi-Instanz-Verwaltung.

Lizenz

MIT

Danksagungen

• jaredhendrickson13 / pfrest — pfSense REST API v2 Paket

• JeremiahChurch — modularer Rewrite (PR #5)

• shawnpetersen — API v2 Endpunkt-Erkennung (PR #3)

• Netgate — pfSense

• FastMCP — MCP-Framework