OPNsense MCP

Stelle deiner Firewall Fragen in einfacher Sprache.

Vier schreibgeschützte Tools für OPNsense — standardmäßig schreibgeschützt und präzise darüber, was verifiziert wurde.

Schnellstart · Tools · Einrichtungsanleitung · Nachweise · Status

Vorschau: ein kleiner MCP-Server, der es einem KI-Assistenten erlaubt, ein OPNsense-System zu inspizieren und — nur wenn explizit aktiviert — eine Art von Firewall-Alias hinter einer Bestätigungs-, Backup- und Audit-Hülle zu erstellen oder zu löschen. Er ist standardmäßig schreibgeschützt. Der gepackte Server wird sowohl gegen ein synthetisches HTTPS-Ziel als auch gegen eine Wegwerf-OPNsense-26-VM getestet.

Fragen in Alltagssprache. Der Server weist den Agenten an, mit Fakten zu beginnen, Netzwerkbegriffe zu erklären, jeweils eine nützliche Rückfrage zu stellen und Beobachtungen klar von Hypothesen zu trennen.

Schnellstart

Schreibgeschützt, etwa 15 Minuten. Erfordert Node.js 22.19 oder neuer innerhalb von Major 22, auf macOS oder Linux.

1. Speichere deine Firewall-Zugangsdaten

npx -y @gabrielion/opnsense-mcp configure

Es fragt nach dem HTTPS-Origin, einem API-Schlüssel und -Geheimnis sowie optional einer CA-Datei. Nichts wird angezeigt und nichts als Prozessargument übergeben. Du musst diesen Schlüssel zuerst erstellen? Die Einrichtungsanleitung führt die OPNsense-Seite mit Screenshots durch.

2. Verbinde deinen Assistenten

claude mcp add opnsense --transport stdio --env READ_ONLY=true -- npx -y @gabrielion/opnsense-mcp

[mcp_servers.opnsense]
command = "npx"
args = ["-y", "@gabrielion/opnsense-mcp"]

[mcp_servers.opnsense.env]
READ_ONLY = "true"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["npx", "-y", "@gabrielion/opnsense-mcp"],
      "environment": { "READ_ONLY": "true" }
    }
  }
}

3. Stelle eine Frage

Wie ist der Status meines OPNsense-Systems?

Welche Dienste laufen auf meiner Firewall?

Führe zuerst /mcp aus: Der Server sollte connected anzeigen. Das Hinzufügen validiert keine Zugangsdaten, daher ist connected das eigentliche Signal.

[!TIP] Keine Firewall zur Hand oder noch nicht bereit, das auf deine zu richten? npm run test:product1b startet eine Wegwerf-OPNsense-VM, erstellt ein eigenes Konto mit minimalen Rechten ohne deine Zugangsdaten, beweist die gesamte Leseoberfläche dagegen und räumt auf.

Related MCP server: OPNsense MCP Server

Was funktioniert jetzt

Standardmäßig stellt der installierte Server vier schreibgeschützte Tools bereit:

• server_status prüft den MCP-Prozess und seinen schreibgeschützten Zustand.

• opn_describe erklärt eine sichtbare Ressource, bevor der Agent sie verwendet.

• opn_get liest die Singleton-Ressource system.status.

• opn_list blättert durch die Sammlungsressourcen core.services und firewall.alias. Bei Aliasen listet es nur die Host-Einträge auf, und die gemeldete Gesamtzahl zählt diese; andere Alias-Typen werden nicht angezeigt.

Drei MCP-Prompts sind ebenfalls immer registriert — diagnose_network_problem, publish_internal_service und block_domain_for_device. Sie erzeugen nur einen schreibgeschützten Vorbereitungsplan; sie führen nichts aus.

READ_ONLY=true ist die Standardeinstellung, und darunter ist kein Schreib-Tool gelistet oder ausführbar.

Zwei experimentelle Schreib-Tools existieren, opn_create und opn_delete, und sie arbeiten nur auf Host-Einträgen von firewall.alias. Drei Bedingungen plus ein unterstützter Transport entscheiden, ob sie überhaupt gelistet werden:

• READ_ONLY=false;

• ENABLED_FEATURE_FLAGS enthält experimental-alias-write;

• ALLOWED_RESOURCES nennt explizit firewall.alias. Eine fehlende oder leere Allow-List autorisiert jede Leseoperation und keine Schreiboperation. Die Allow-List filtert auch Lesevorgänge, also nenne jeden Bereich, den du weiterhin möchtest, zum Beispiel ALLOWED_RESOURCES=server.status,system.status,core.services,firewall.alias;

• der Transport ist stdio oder Streamable HTTP. Legacy-SSE listet oder sendet sie nie.

Eine vierte Bedingung regelt den Aufruf und nicht die Auflistung: Der Client muss Form-Elicitation ausgehandelt haben. Ein Client ohne diese sieht die Tools weiterhin und wird bei jedem Versuch mit CONFIRMATION_UNAVAILABLE abgewiesen, vor jeder Herausforderung oder Schreiboperation.

Jeder Schreibvorgang durchläuft diese feste Hülle in dieser Reihenfolge: Autorisierung, eine menschliche Bestätigung, die die Änderung benennt, eine exklusive Sperre auf dem Ziel, ein nebenwirkungsfreier Preflight, eine geschwärzte Audit-Absicht, ein verifiziertes Backup vor der Änderung, eine erneute Prüfung, dass der beobachtete Zustand sich nicht bewegt hat, der Schreibvorgang, eine Ergebnisverifizierung, ein finaler Audit-Datensatz und die Freigabe der Sperre. Jeder Fehler nach dem Backup bewahrt es auf und stellt nie blind wieder her.

Diese Schreibvorgänge sind aus gutem Grund experimentell. Das Backup vor der Änderung wird in ein prozesslokales temporäres Verzeichnis geschrieben, das beim Herunterfahren des Servers gelöscht wird, sodass es danach nicht eingesehen werden kann. Das Audit ist ein In-Memory-Ring, der nur die letzten 1024 Datensätze hält (zwei pro Schreibvorgang), ohne persistierte Form und ohne Tool, das es liest. Die Sperre ist prozesslokal, sodass sich zwei Server, die auf dieselbe Firewall zeigen, nicht gegenseitig ausschließen.

Was die Hülle garantiert, ist eng, aber real: Ein Schreibvorgang wird verweigert, es sei denn, ein verifiziertes Backup und eine Audit-Absicht wurden zuerst aufgezeichnet. Es gibt keine Wiederherstellung und kein Rollback — wenn ein Fehler nach der Anwendung der Änderung auftritt, bleibt die Änderung angewendet und die Wiederherstellung erfolgt manuell über die eigene Konfigurationshistorie von OPNsense. Diesen Zustand dauerhaft zu machen, ist der nächste Meilenstein.

Schneller lokaler Beweis

Anforderungen: Node.js 22.19 oder neuer innerhalb von Major 22, npm, macOS oder Linux.

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
npm ci --ignore-scripts &&
npm run test:product1a &&
npm run build

npm run test:product1a erstellt ein sauberes npm-Tarball, installiert es in einem isolierten Consumer-Projekt, verbindet es mit einem separat gehaltenen synthetischen HTTPS-OPNsense-Ziel, ruft alle drei OPNsense-Tools über rohes MCP-stdio auf, prüft, dass Geheimnisse nie erscheinen, schließt bei EOF und entfernt alle Fixtures.

Verbinde deine OPNsense-Instanz

Der unterstützte Weg, Zugangsdaten bereitzustellen, ist der interaktive Befehl, der die private Datei für dich mit den richtigen Besitz- und Modusrechten schreibt. Aus einem Klon ist es ein Unterbefehl des gebauten Einstiegspunkts:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
node dist/main.js configure

Aus der Registry installiert, ist derselbe Unterbefehl npx -y @gabrielion/opnsense-mcp configure.

Er fragt nach dem HTTPS-Origin, API-Schlüssel, API-Geheimnis sowie der optionalen CA-Datei und dem TLS-Servernamen; die Geheimnisse werden nie angezeigt und erscheinen nie in einem Prozessargument. Er weigert sich, unter Windows zu laufen, und lehnt jedes Argument ab.

Er schreibt immer in den Plattformpfad und ignoriert OPNSENSE_CONFIG_FILE, das eine serverseitige Variable ist:

• macOS: ~/Library/Application Support/opnsense-mcp/config.json;

• Linux: $XDG_CONFIG_HOME/opnsense-mcp/config.json, sonst ~/.config/opnsense-mcp/config.json.

Der Server findet dieselben Pfade, daher wird die Variable nur benötigt, um eine anderswo gespeicherte Datei zu lesen. Jedes Verzeichnis, das er besitzt, wird mit Modus 0700 und die Datei mit Modus 0600 erstellt; Symlinks, fremde Besitzer und unsichere Vorfahren werden abgelehnt.

Zwei praktische Grenzen: Er überschreibt nie eine bestehende Konfiguration, also rotiere einen Schlüssel, indem du die Datei zuerst löschst; und er benötigt ein echtes Terminal auf beiden Strömen, sodass er nicht gepipet oder in CI ausgeführt werden kann. Jeder Fehler gibt absichtlich das einzelne Wort Error aus — die Diagnostik ist bewusst undurchsichtig, damit nichts über den privaten Pfad oder die Zugangsdaten durchsickert.

Alternativ kannst du die JSON-Datei selbst außerhalb des Repositorys erstellen und mit Modus 0600 schützen:

{
  "url": "https://192.0.2.1",
  "apiKey": "your-dedicated-read-only-api-key",
  "apiSecret": "your-api-secret",
  "caFile": "/absolute/path/to/your-ca.pem",
  "tlsServerName": "firewall.example.internal"
}

Die Datei muss eine reguläre, nicht-symlinkische Datei sein, die dem aktuellen Benutzer gehört, an einem absoluten Pfad, mit exakt Modus 0600, exakt einem Hardlink und höchstens 16 KiB. 0400 wird ebenfalls abgelehnt. url muss ein exakter HTTPS-Origin sein. caFile ist optional, wenn das Firewall-Zertifikat bereits zu einer vertrauenswürdigen CA verkettet. tlsServerName ist optional, wenn die URL eine IP-Adresse verwendet, das verifizierte Zertifikat aber einen DNS-Namen verwendet. TLS-Verifizierung bleibt immer aktiviert. Verwende einen dedizierten OPNsense-Schlüssel mit minimalen Rechten; füge keine Zugangsdaten in Chat oder Befehlsargumente ein.

Transports. stdio ist die Standardeinstellung und der einzige Transport, der von den gepackten Beweisen Ende-zu-Ende ausgeführt wird; dist/main.js startet immer stdio. Ein Streamable-HTTP-Transport existiert als separater Einstiegspunkt (npm run start:http) hinter MCP_HTTP_ENABLED, gebunden an Loopback mit einer Host/Origin-Allow-List und einem Bearer-MCP_HTTP_TOKEN von mindestens 32 Zeichen; er ist nicht durch einen Client-Smoke abgedeckt, daher wird keine Client-Unterstützungsbehauptung für ihn aufgestellt. Eine Legacy-SSE-Kompatibilitätsoberfläche existiert hinter MCP_LEGACY_SSE_ENABLED, die zusätzlich MCP_HTTP_ENABLED=true erfordert — alleiniges Setzen ist ein Startfehler — und die bestätigungsgestützten Schreib-Tools nie offenlegt.

Um den protokollsauberen stdio-Server direkt auszuführen:

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
OPNSENSE_CONFIG_FILE="/absolute/path/to/opnsense.json" READ_ONLY=true node dist/main.js

Richte Entwicklung oder Tests nie auf eine Produktionsfirewall. Verwende für Live-Arbeit den Wegwerf-VM-Beweis unten.

Wegwerf-OPNsense-26-Beweis

Installiere auf macOS oder Linux QEMU plus Node.js 22 und führe dann aus:

npm run vm:doctor
npm run test:product1b

vm:doctor meldet jede fehlende Host-Abhängigkeit, ohne die Maschine zu verändern. test:product1b besitzt den gesamten Live-Test: Es verifiziert und cached das festgepinnte offizielle OPNsense-26.7-nano-Image, startet eine lokale VM, erstellt über die serielle Konsole einen Wegwerf-API-Benutzer mit minimalen Rechten ohne Operator-Zugangsdaten, packt und installiert dieses npm-Paket, ruft server_status, opn_describe system.status, opn_get system.status und opn_list core.services über eine MCP-Sitzung auf, stoppt dann die VM und entfernt das Overlay, die API-Zugangsdaten, das Zertifikat und das temporäre Paket. Der erste Lauf lädt ein etwa 557 MB großes Archiv herunter und erstellt ein 3 GiB großes schreibgeschütztes Basisimage im Benutzer-Cache.

Der historische Product-1B-Nachweis bleibt der Beweis für nur zwei Remote-Aufrufe: GET /api/core/system/status und POST /api/core/service/search. Sein bereinigter maschinenlesbarer Nachweis zeichnet auch seinen exakten Host, QEMU, Firmware, Transport und Bereinigungsprüfungen auf, ohne Firewall-Daten oder Zugangsdaten zu behalten.

Die Alias-Schreibimplementierung zielt auf GET /api/core/backup/download/this für das Backup vor der Änderung, dann POST /api/firewall/alias/searchItem, addItem oder delItem/{uuid}, dann den reconfigure-Apply. Diese Endpunktdetails haben deterministische synthetische Zielabdeckung. Product 3 beweist auf einer Wegwerf-VM nur Folgendes: die beschreibbare Oberfläche und diesen exakten firewall.alias-Lebenszyklus: abwesend, erstellen, vorhanden, löschen, abwesend, gefolgt von VM-Bereinigung und einer rückstandsfreien Prüfung. Die commit-gebundene Product-3-VM-Bescheinigung zeichnet den getesteten Commit und Baum, das festgepinnte Firmware-Image, die Richtlinieneingaben und die festen Lebenszyklusprüfungen auf, ohne Firewall-Daten oder Zugangsdaten zu behalten. Die Product-3-Bescheinigung beweist keine Produktionsnutzung, dauerhaften Zustand, dauerhafte Backups, eine dauerhafte Audit-Spur, Wiederherstellung oder automatisches Rollback.

Der Wiederherstellungs-Roundtrip setzt dieselbe Alias-Mutation zusätzlich direkt über die Konsole der Wegwerf-VM zurück — nicht über die API — und beobachtet dann die API erneut, um zu prüfen, dass die Mutation verschwunden ist. Die Wiederherstellungs-Roundtrip-Product-3-VM-Bescheinigung zeichnet den getesteten Commit und Baum, dasselbe festgepinnte Firmware-Image und dieselben Richtlinieneingaben, die Alias-Lebenszyklusprüfungen und die Backup-wiederhergestellten und zustandsrückgesetzten Prüfungen auf, wiederum ohne Firewall-Daten oder Zugangsdaten zu behalten, erstellt mit node scripts/vm/product3-restore.mjs --attestation-out "$PWD/docs/evidence/product3-restore-vm.json".

Rechte des Wegwerf-Kontos. Die Konten werden mit genau diesen Standard-ACLs erstellt und sonst nichts. Beide ACL-Profile haben jetzt Live-Nachweise nur in ihren exakten Szenarien: das Nur-Lese-Profil in Produkt 1B und das Alias-Schreib-Profil in Produkt 3.

• Nur-Lese-Konto: page-system-status, page-status-services, user-config-readonly;

• Alias-Schreib-Konto: page-system-status, page-status-services, page-diagnostics-configurationhistory, page-firewall-alias-edit.

user-config-readonly ist im Alias-Schreib-Konto bewusst nicht enthalten: Wir haben beobachtet, dass es den OPNsense-Controller für das veränderbare Modell dazu bringt, Alias-Speicherungen abzulehnen. page-diagnostics-configurationhistory wird für die Konfigurations-Backup-Anfrage vor der Änderung gewährt. Beide Aussagen stammen aus unserer eigenen Bootstrap-Erfahrung, nicht aus einer zitierten Upstream-Zuordnung.

OpenCode

Fügen Sie eine projektweite opencode.json hinzu (ersetzen Sie beide absoluten Pfade):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["node", "/absolute/path/to/OPNSenseMCP/dist/main.js"],
      "environment": {
        "READ_ONLY": "true",
        "OPNSENSE_CONFIG_FILE": "/absolute/path/to/opnsense.json"
      }
    }
  }
}

Führen Sie dann opencode mcp list aus; opnsense sollte verbunden sein. Die eingecheckten Smoke-Nachweise decken nur OpenCode 1.18.16 mit opencode/deepseek-v4-flash-free gegen das installierte Tarball und das synthetische HTTPS-Ziel ab. Sie erfassen Tool-/Ergebnis-Digests, keine Firewall-Daten oder Anmeldeinformationen. Siehe die maschinenlesbaren Nachweise.

Andere MCP-Clients können denselben stdio-Befehl starten, aber es wird keine client-spezifische Unterstützungsbehauptung aufgestellt, bis deren eigener versionierter Smoke-Test besteht.

Wie diese Vorschau getestet wird

• Strikte TypeScript-, Formatierungs-, Lint-, Lizenzkopf- und deterministische Unit-/Integrationstests.

• Sauberes npm pack/install plus TLS, Basisauthentifizierung, Antwortvalidierung, Geheimnis-Schwärzung, Herunterfahren und Bereinigung gegen ein synthetisches Ziel.

• Historisches sauberes npm pack/install gegen eine Wegwerf-OPNsense-26.1.6-VM für die beiden Produkt-1B-Fernaufrufe, einschließlich VM-Besitz, Integrität des gepinnten Images, isolierte Anmeldeinformationen, TLS-Pinning und umgekehrte Bereinigung.

• Ein commit-gebundener Produkt-3-Lauf gegen eine Wegwerf-OPNsense-26.7-VM für die beschreibbare Oberfläche und den exakten Host-Alias-Lebenszyklus: abwesend, erstellen, vorhanden, löschen, abwesend, gefolgt von VM-Bereinigung und einer rückstandsfreien Prüfung.

• Eine hermetische Paketinstallation für den synthetischen Zielnachweis und beide VM-Runner: Der Verbraucher löst jede Abhängigkeit aus einer sperr-abgeleiteten Loopback-only-npm-Registry auf, mit leerem Cache und unerreichbaren Proxys, sodass kein Internetzugriff beteiligt ist und keine Upstream-Version das Installierte ändern kann.

• Gezielte MCP-Interoperabilitätsprüfungen für die Protokollversionen 2025-11-25 und den Entwurf 2026-07-28.

• Ein echter OpenCode-1.18.16-Routing-Smoke mit opencode/deepseek-v4-flash-free.

Der vollständige Entwicklungsstand und die Maschine-zu-Maschine-Übergabe sind in docs/project-status.md dokumentiert. Die geplante kanonische Agentenbewertung ist im DeepEval- und OPNsense-Bewertungsdesign spezifiziert: Sie wird die MCP-Toolnutzung und die endgültige Antwort von Claude Code bewerten, während sie separat ein deterministisches MCP-Rücklesen des Wegwerf-VM-Zustands erfordert. Diese Tests und jede Benchmark-Punktzahl sind noch nicht implementiert oder beansprucht.

Zusammen decken diese Prüfungen das Paket, den synthetischen Lesepfad, die beiden genannten historischen Produkt-1B-Fernaufrufe und nicht mehr als den oben genannten begrenzten Lebenszyklus ab. Sie beweisen nicht:

• öffentliche DNS-, ACME- oder HAProxy-Exposition im Internet;

• Verhalten gegenüber einer Produktionsfirewall;

• dauerhafte Backups oder eine dauerhafte Prüfspur: Beides existiert, aber nur für die Lebensdauer des Prozesses;

• Wiederherstellung oder ein automatisches Rollback einer angewendeten Änderung;

• Schreibvorgänge auf etwas anderes als Host-Einträge von firewall.alias;

• jede Garantie über die ersten 100 Host-Aliase hinaus: Der Zustands-Digest vor der Änderung und das Rücklesen lesen beide eine einzelne Seite von 100, sodass darüber hinaus ein Erstellen ein unverifiziertes Ergebnis melden kann und ein Löschen nur beweisen kann, dass der Eintrag nicht auf der gelesenen Seite war;

• native Windows-Installation oder Client-Betrieb;

• eine vollständige agentische Benchmark oder eine Benchmark-Punktzahl.

Roher API-Dispatch, freie Shell/SSH, Bulk-IaC, ein Dashboard und breite Legacy-Parität fehlen.

Produkt-Roadmap und Beispielanfragen

Die Mutations-Sicherheitshülle — eingeschränkte Autorisierung, menschliche Bestätigung, verifiziertes Backup, geschwärzte Prüfung, Ergebnisverifizierung, Fail-Closed-Bereinigung — ist implementiert und gegen ein synthetisches HTTPS-Ziel nachgewiesen. Der nächste Meilenstein ist, ihren Zustand dauerhaft zu machen: eine persistente Zustandswurzel, eine Interprozesssperre, eine Append-only-Prüfung und einen lokalen reconcile-Befehl, damit die Garantien einen Neustart überleben. Erst dann kann das experimental-Label für Alias-Schreibvorgänge überdacht werden.

Spätere geführte Arbeitsabläufe sind bewusst Ziele auf Benutzerebene, zum Beispiel:

• „Mein Laptop verliert jeden Abend die Internetverbindung. Können Sie das untersuchen und erklären, was Sie finden?“

• „Blockieren Sie TikTok nur für das Tablet meines Kindes, ohne die anderen Geräte zu beeinträchtigen.“

• „Veröffentlichen Sie diesen Dienst intern mit einem freundlichen DNS-Namen, einem internen Zertifikat und einem Reverse-Proxy.“

Diese drei Arbeitsabläufe sind Roadmap-Beispiele, keine Produkt-1A-Behauptungen. Internetgerichtete Veröffentlichung mit öffentlichem DNS, Let's Encrypt und HAProxy ist ein langfristiger Labormeilenstein nach sicheren Schreibvorgängen und Private-VM-Abdeckung.

Verteilungsstatus: auf npm als @gabrielion/opnsense-mcp veröffentlicht, sodass npx -y @gabrielion/opnsense-mcp den veröffentlichten Server ausführt; eine Installation über eine Git-URL erstellt weiterhin ihr eigenes dist/ über das prepare-Skript. Die verpackten Nachweise installieren in jedem Fall ein lokal erstelltes Tarball, das von einer sperr-abgeleiteten Loopback-Registry bereitgestellt wird, sodass sie diesen Baum und keine Registry-Kopie testen. Es wird noch keine Versions- oder Upgrade-Garantie angeboten.

Plattformstatus: macOS und Linux sind die derzeit verifizierten Entwicklungshosts. Natives Windows bleibt ein gefordertes Produktziel, aber Paket- und Client-Unterstützung werden erst beansprucht, wenn das spätere windows-2025-Gate besteht.

Lizenz und Marke

Lizenziert unter AGPL-3.0-or-later; siehe LICENSE. Die AGPL erlaubt kommerzielle Nutzung, verlangt aber die Verfügbarkeit des abgedeckten Quellcodes, auch für Netzwerknutzung. OPNsense ist eine Marke von Deciso B.V. Dieses unabhängige Projekt ist nicht mit Deciso B.V. oder dem OPNsense-Projekt verbunden, wird von ihnen nicht gesponsert und nicht unterstützt.