OPNsense MCP Server

Ein sicherer Model Context Protocol-Server (MCP) zur Verwaltung von OPNsense-Firewalls über KI-Assistenten wie Claude Code, Cursor und andere MCP-kompatible Tools.

81 Tools in 10 Bereichen: System, Firewall, Netzwerk, DNS, DHCP, VPN, HAProxy, Dienste, Diagnose und Sicherheit.

Voraussetzungen

• Python 3.11+

• OPNsense 24.7 oder neuer – der MCP-Server nutzt die MVC-basierten API-Endpunkte, die in OPNsense 24.7 eingeführt wurden. Ältere Versionen verwenden eine andere API-Struktur, die nicht kompatibel ist. Der Server erkennt die OPNsense-Version beim ersten Verbindungsaufbau automatisch und wählt die korrekte Endpunkt-Benennung (camelCase für vor 25.7, snake_case für 25.7+). OPNsense 26.x wird vollständig unterstützt, einschließlich des geänderten Firmware-Status-Antwortformats.

Related MCP server: OPNsense MCP Server

Sicherheitsmodell

Dieser MCP-Server wurde mit Sicherheit als oberste Priorität entwickelt:

• Standardmäßig schreibgeschützt – Schreiboperationen erfordern eine explizite Freigabe über OPNSENSE_ALLOW_WRITES=true

• Savepoint/Rollback (nur OPNsense < 26.7) – wo OPNsense weiterhin die Savepoint-API anbietet, nutzen Firewall-Änderungen den integrierten 60-Sekunden-Automatik-Rollback; Änderungen müssen explizit bestätigt werden, andernfalls werden sie automatisch zurückgesetzt. OPNsense 26.7 hat diese API upstream entfernt – der Server erkennt den fehlenden Endpunkt zur Laufzeit und wendet Firewall-Änderungen ohne automatischen Rollback sofort an.

• Endpunkt-Blockliste – gefährliche Endpunkte (halt, reboot, poweroff, firmware update/upgrade) sind auf Client-Ebene der API hart blockiert und können niemals aufgerufen werden.

• Nur API – kein SSH-Zugriff, keine Befehlsausführung, keine direkte Manipulation von Konfigurationsdateien.

• Lokaler Transport – nur STDIO, keine netzwerkexponierten HTTP/SSE-Endpunkte.

• Keine Offenlegung von Zugangsdaten – API-Schlüssel werden niemals in Tool-Ausgaben, Protokollen oder Fehlermeldungen angezeigt.

• Eingabevalidierung – Hostname-Parameter werden gegen Shell-Metazeichen-Injection validiert.

• Entfernung sensibler Daten – Konfigurationssicherungen entfernen standardmäßig Passwörter und Schlüssel.

Schnellstart

1. OPNsense-API-Schlüssel erstellen

1. Melden Sie sich in der Weboberfläche Ihrer OPNsense an.

2. Gehen Sie zu System > Zugriff > Benutzer.

3. Bearbeiten Sie entweder einen vorhandenen Benutzer oder erstellen Sie einen dedizierten API-Benutzer:

   • Für den Produktiveinsatz erstellen Sie einen dedizierten Benutzer (z. B. mcp-api) mit nur den benötigten Berechtigungen.

   • Für reinen Lesezugriff weisen Sie den Benutzer einer Gruppe mit Lesezugriff auf die API zu.

4. Scrollen Sie zum Abschnitt API-Schlüssel und klicken Sie auf die Schaltfläche +.

5. Ein Schlüssel/Geheimnis-Paar wird generiert und eine Datei (apikey.txt) wird heruntergeladen.

6. Die Datei enthält zwei Zeilen – key=ihr-api-schluessel-hier und secret=ihr-geheimnis-hier.

7. Bewahren Sie diese Zugangsdaten sicher auf – das Geheimnis kann später nicht erneut von OPNsense abgerufen werden.

Tipp: Für einen reinen Leseaufbau (empfohlen für den Einstieg) müssen Sie keine Berechtigungen ändern – der Standard-API-Zugriff ist für alle Lesetools ausreichend.

2. Installation

# Using pip
pip install opnsense-mcp-server

# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server

# Using Docker
docker pull uhlenheide/opnsense-mcp-server

# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .

Docker-Image: Das offizielle Image ist uhlenheide/opnsense-mcp-server, veröffentlicht aus diesem Repository durch .github/workflows/publish-docker.yml bei jedem v*-Tag. Es gibt kein lucamarien/opnsense-mcp-server-Image – frühere README-Versionen nannten es fälschlicherweise so.

3. Ihren KI-Assistenten konfigurieren

Claude Code

Fügen Sie zur .mcp.json Ihres Projekts hinzu:

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false",
        "OPNSENSE_ALLOW_WRITES": "false"
      }
    }
  }
}

Alternative: Verwenden Sie "command": "python", "args": ["-m", "opnsense_mcp"], falls die opnsense-mcp-CLI nicht in Ihrem PATH ist.

Oder fügen Sie es global zur ~/.claude/claude_code_config.json hinzu.

Claude Code (Docker)

{
  "mcpServers": {
    "opnsense": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPNSENSE_URL=https://192.168.1.1/api",
        "-e", "OPNSENSE_API_KEY=your-api-key-here",
        "-e", "OPNSENSE_API_SECRET=your-api-secret-here",
        "-e", "OPNSENSE_VERIFY_SSL=false",
        "-e", "OPNSENSE_ALLOW_WRITES=false",
        "uhlenheide/opnsense-mcp-server"
      ]
    }
  }
}

Cursor

Fügen Sie es zu Ihren Cursor-MCP-Einstellungen hinzu (Einstellungen > MCP):

{
  "mcpServers": {
    "opnsense": {
      "command": "opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1/api",
        "OPNSENSE_API_KEY": "your-api-key-here",
        "OPNSENSE_API_SECRET": "your-api-secret-here",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Konfiguration

Benutzerdefinierte Ports: Wenn die OPNsense-Weboberfläche auf einem nicht standardmäßigen Port läuft (z. B. 10443), geben Sie ihn in der URL an: https://192.168.1.1:10443/api

Verfügbare Tools (81)

System (7 Tools)

Netzwerk (5 Tools)

Firewall (21 Tools)

| Werkzeug | Beschreibung schreiben/td> (Writes "Writes "Writes" Writes | No" | No ( (; ( ( ( ( ( (; ( ( ( Translate the entire table rows.

We'll produce the entire output with translated descriptions.

We'll keep the table structure exactly (same number of "| and das: "Writes "Writes ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( (1. We'll output the entire translated text.

We'll write the entire Markdown.

We'll output the entire translated content, translated descriptions only, and headings and headings and notes, everything else verbatim except descriptions and headings and notes.| Tool | Beschreibung | Schreibend | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | opn_list_firewall_rules | MVC-Firewall-Filterregeln auflisten. Parameter: search, Zeitlimit | Nein | | opn_list_firewall_aliases | Aliasdefinitionen auflisten (IP-Listen, Portgruppen, GeoIP, URLs). Parameter: search, limit | Nein | | opn_list_nat_rules | NAT-Portweiterleitungsregeln (DNAT) auflisten. Parameter: search, limit | Nein | | opn_list_firewall_categories | Firewall-Regelkategorien und deren UUIDs auflisten. Parameter: Rollen, search, limit | Nein | | opn_firewall_log | Aktuelle Firewall-Protokolleinträge mit clientseitiger Filterung. Parameter: source_ip, destination_ip, action, interface, limit | Nein | | opn_confirm_changes | Ausstehende Änderungen bestätigen und damit das 60-Sekunden-Auto-Rollback abbrechen (OPNsense < 26.7; ein No-Op, das auf 26.7+ not_applicable zurückgibt). Parameter: revision | Ja | | opn_toggle_firewall_rule | Aktiviert/Deaktiviert den Zustand einer Regel mit Savepoint (OPNsense < 26.7). Parameter: uuid | Ja | | opn_add_firewall_rule | Neue Filterregel mit Savepoint erstellen (OPNsense < 26.7). Parameter: action, direction, interface, ip_protocol, protocol, source_net, destination_net, destination_port, description | Ja | | opn_delete_firewall_rule | Filterregel per UUID mit Savepoint löschen (OPNsense < 26.7). Parameter: uuid | Ja | | opn_add_alias | Neuen Alias erstellen. Parameter: name, alias_type, content, description | Ja | | opn_add_nat_rule | NAT-Portweiterleitungsregel mit Savepoint erstellen (OPNsense < 26.7). Parameter: destination_port, target_ip, interface, protocol, target_port, description | Ja | | opn_add_firewall_category | Neue Firewall-Regelkategorie erstellen. Parameter: name, color | Ja | | opn_add_icmpv6_rules | Erstellen Sie eine neue Firewall-Regelkategorie. Parameter: name, color | Ja | | opn_add_alias | Neuen Alias erstellen. Parameter: name, alias_type, content, description | Ja | | opn_add_nat_rule | NAT-Portweiterleitungsregel mit Savepoint (OPNsense < 26.7). Parameter: destination_port, target_ip, interface, protocol, target_port, description ########## 相似三角形ABC中，点，则的周长是（2019-看，求阴影部分的面积是（.NET 4.0. 0.0f; return 0; } }

VPN (3 Tools)

HAProxy (8 Tools)

Vollständige Konfigurationsverwaltung für den HAProxy-Lastverteiler (erfordert das os-haproxy-Plugin).

Hinweis: HAProxy-Änderungen verwenden keinen Savepoint-Schutz — sie werden sofort beim Neukonfigurieren angewendet. Rufen Sie vor opn_reconfigure_haproxy immer opn_haproxy_configtest auf.

Dienste (11 Tools)

Diagnose (4 Tools)

Sicherheit (1 Tool)

Schreiboperationen und Savepoints

Schreiboperationen erfordern OPNSENSE_ALLOW_WRITES=true. Auf OPNsense < 26.7 laufen Firewall-Änderungen zusätzlich über den Savepoint-Mechanismus von OPNsense:

1. Vor jeder Firewall-Änderung wird automatisch ein Savepoint erstellt

2. Die Änderung wird angewendet (Regel umschalten, hinzufügen oder löschen)

3. Ein 60-Sekunden-Countdown startet — wenn nicht bestätigt wird, macht OPNsense die Änderung automatisch rückgängig

4. Verwenden Sie opn_confirm_changes mit der zurückgegebenen revision, um Änderungen dauerhaft zu machen

Auf diesen Versionen wird eine fehlerhafte Firewall-Änderung durch eine KI-Assistenten, die Sie aussperrt, automatisch innerhalb von 60 Sekunden zurückgesetzt.

OPNsense 26.7 hat die Savepoint-/Rollback-API upstream entfernt, daher gibt es auf 26.7+ kein automatisches Zurücksetzen. Der Server kodiert keine Versionsgrenze fest: Er testet den Savepoint-Endpunkt beim ersten Firewall-Schreibvorgang und, wenn OPNsense antwortet, dass der Endpunkt nicht existiert, wechselt er für den Rest der Sitzung zur direkten Anwendung. Prüfen Sie opn_mcp_info — das Feld savepoint_support meldet true, false oder null, wenn noch kein Schreibvorgang getestet wurde. Schreib-Tools geben dann eine leere revision zurück, opn_confirm_changes antwortet mit status: "not_applicable", und jede Firewall-Änderung ist sofort und dauerhaft.

Warnung: Erstellen Sie auf OPNsense 26.7+ ein Konfigurations-Backup (opn_download_config oder System > Konfiguration > Backups), bevor Sie Schreibzugriff aktivieren, und behalten Sie Out-of-Band-Zugriff auf das Gerät — eine Regel, die Sie aussperrt, wird sich nicht von selbst zurücksetzen.

Hinweis: opn_reconfigure_unbound, opn_reconfigure_haproxy, opn_reconfigure_ddclient, opn_reconfigure_dnsmasq und opn_configure_mdns_repeater erfordern Schreibzugriff, verwenden aber keine Savepoints — sie wenden Dienstkonfigurationsänderungen an und sind nicht automatisch rückgängig zu machen.

IPv6-Unterstützung

Vollständig automatisiert über MCP

• IPv6-Firewall-Regeln — Regeln mit ip_protocol="inet6" erstellen (auf OPNsense < 26.7 Savepoint-geschützt)

• HAProxy-IPv6-Bindings — Frontends mit [::]:443- oder [2001:db8::1]:443-Bind-Adressen

• HAProxy-IPv6-Backends — Server mit IPv6-Adressen, resolvePrefer: ipv6 auf Backends

• Dynamisches DNS mit IPv6 — DDNS-Konten mit IPv6-fähigen CheckIP-Methoden

• DHCPv6-Bereiche (dnsmasq) — IPv6-DHCP-Bereiche mit Router-Advertisement-Konfiguration

• DNS-AAAA-Einträge — Unbound-Host-Overrides mit IPv6-Adressen

• IPv6-Diagnose — Traceroute mit ip_version="6", Ping über Hostname

Erfordert manuelle GUI-Konfiguration

Diese Einstellungen haben keine MVC-API-Unterstützung in OPNsense und müssen über die Web-GUI konfiguriert werden:

• WAN-IPv6-Einrichtung — PPPoE mit DHCPv6-Präfix-Delegation, statisches IPv6, SLAAC

• LAN-IPv6-Adressierung — Track-Interface-Modus, statische /64-Zuweisung, Präfix-ID

• Interface-Zuweisung — Zuweisung physischer Ports zu WAN/LAN/OPT-Rollen

• 6to4/6rd-Tunnel — Übergangs-Tunnelmechanismen

Bekannte Einschränkungen

• ISC DHCP / Kea DHCPv6: Nicht implementiert. Nur dnsmasq (die moderne Standardoption) wird für DHCPv6-Bereiche und Router Advertisements unterstützt. ISC DHCP ist veraltet; die Kea-DHCPv6-Lease-Sichtbarkeit ist in der API eingeschränkt.

• radvd: Nicht als separates Tool-Set implementiert. Dnsmasq übernimmt Router Advertisements nativ über die Bereichskonfiguration. Pro Interface sollte nur ein RA-Daemon laufen.

• Dual-Stack-Firewall-Regeln: inet46 (Dual-Stack) funktioniert korrekt in MVC-API-Regeln (opn_add_firewall_rule). Allerdings erzeugt inet46 in Legacy-XML-Filterregeln (GUI) stillschweigend keine PF-Ausgabe — dies ist ein bekannter OPNsense-Bug, der nur Legacy-Regeln betrifft.

• Legacy-GUI-Regeln: Über die traditionelle OPNsense-GUI erstellte Firewall-Regeln sind über die MVC-API nicht zugänglich. Verwenden Sie opn_get_config_section("filter") für den Nur-Lese-Zugriff.

Empfohlener IPv6-Migrations-Workflow

1. Manuell (GUI): WAN-IPv6 konfigurieren (DHCPv6-PD vom ISP oder statisch)

2. Manuell (GUI): LAN-Interfaces konfigurieren (Track-Interface-Modus für Präfix-Delegation)

3. MCP: Router Advertisements über opn_add_dnsmasq_range mit RA-Flags konfigurieren

4. MCP: IPv6-Firewall-Regeln erstellen (ICMPv6 muss für NDP/RA/PMTUD erlaubt sein)

5. MCP: IPv6-DNS-Einträge über opn_add_dns_override hinzufügen

6. MCP: Dynamisches DNS mit IPv6-CheckIP-Methode konfigurieren

7. MCP: IPv6-Bind-Adressen zu HAProxy-Frontends hinzufügen

8. MCP: Mit opn_ping, opn_traceroute (ip_version="6"), opn_gateway_status verifizieren

Versionskompatibilität

Der Server erkennt die OPNsense-Version bei der ersten Verbindung automatisch und wählt die korrekte API-Endpunkt-Namenskonvention (camelCase für vor 25.7, snake_case für 25.7+).

Hinweis zu Firewall-Regeln: opn_list_firewall_rules zeigt Regeln, die über die MVC-/Automatisierungs-API verwaltet werden. Über die OPNsense-GUI konfigurierte Regeln verwenden ein Legacy-Format, das über diese API nicht zugänglich ist. Dies ist eine bekannte OPNsense-Einschränkung.

Fehlerbehebung

Verbindungsprobleme

„Verbindung abgelehnt" oder Timeout-Fehler

• Stellen Sie sicher, dass OPNSENSE_URL mit /api endet (z. B. https://192.168.1.1/api)

• Wenn ein nicht standardmäßiger Port verwendet wird, fügen Sie ihn hinzu: https://192.168.1.1:10443/api

• Stellen Sie sicher, dass die OPNsense-Web-GUI von dem Rechner aus erreichbar ist, auf dem der MCP-Server läuft

SSL-Zertifikatsfehler

• Für selbstsignierte Zertifikate (Standard-OPNsense-Einrichtung) setzen Sie OPNSENSE_VERIFY_SSL=false

• Für die Produktion installieren Sie ein ordnungsgemäßes Zertifikat auf OPNsense und behalten Sie OPNSENSE_VERIFY_SSL=true bei

Authentifizierungsprobleme

401 Nicht autorisiert

• Überprüfen Sie, ob OPNSENSE_API_KEY und OPNSENSE_API_SECRET korrekt sind

• API-Schlüssel sind case-sensitiv — kopieren Sie sie exakt aus der heruntergeladenen apikey.txt

• Überprüfen Sie, ob der API-Benutzer in OPNsense nicht deaktiviert ist

• Überprüfen Sie, ob der API-Benutzer ausreichende Berechtigungen für die gewünschten Operationen hat

403 Verboten

• Dem API-Benutzer fehlen möglicherweise Berechtigungen für den angeforderten Endpunkt

• Für Schreiboperationen stellen Sie sicher, dass OPNSENSE_ALLOW_WRITES=true gesetzt ist

Toolspezifische Probleme

opn_list_firewall_rules liefert leere Ergebnisse

• Dieses Tool zeigt nur MVC-/Automatisierungsregeln, keine Legacy-GUI-Regeln

• Erstellen Sie Regeln über die Automatisierungs-API oder opn_add_firewall_rule, um sie zu sehen

opn_ping läuft in einen Timeout

• Die Firewall hat möglicherweise keine Route zum Zielhost

• Überprüfen Sie den Gateway-Status mit opn_gateway_status

• Standard-Timeout beträgt 30 Sekunden (30 Abfragezyklen)

opn_download_config zeigt [REDACTED]-Werte

• Dies ist das Standardverhalten aus Sicherheitsgründen. Übergeben Sie include_sensitive=true, um Passwörter und Schlüssel einzuschließen (in KI-Konversationen mit Vorsicht verwenden)

Schreiboperationen schlagen mit „writes not enabled" fehl

• Setzen Sie OPNSENSE_ALLOW_WRITES=true in Ihrer MCP-Server-Konfiguration

• Dies ist aus Sicherheitsgründen standardmäßig absichtlich deaktiviert

Savepoint-Bestätigung schlägt fehl

• Der Parameter revision muss exakt mit dem übereinstimmen, was von der Schreiboperation zurückgegeben wurde

• Bestätigungen müssen innerhalb von 60 Sekunden erfolgen, sonst wird die Änderung automatisch zurückgesetzt

• Auf OPNsense 26.7+ gibt es keine Savepoint-API: Schreib-Tools geben eine leere revision zurück und opn_confirm_changes gibt status: "not_applicable" zurück. Das ist erwartet, kein Fehler — die Änderung wurde bereits dauerhaft angewendet

Diagnosebefehle

Wenn Sie den MCP-Server debuggen müssen:

# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status

# Run the server directly
python -m opnsense_mcp

# Run tests to verify installation
pytest -v

Entwicklung

# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"

# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v

# Full CI pipeline (lint, format, type check, security scan, tests)
make validate

# Individual checks
ruff check src/ tests/          # Lint (includes bandit security checks)
ruff format src/ tests/          # Format
mypy src/ --strict               # Type checking

Best Practices

Domänenspezifische Anleitungen für häufige Firewall-Konfigurationsaufgaben:

• WhatsApp-Anruf-Firewall-Regeln — WhatsApp-Sprach-/Videoanrufe durch eine Default-Deny-Firewall mithilfe von URL-Tabellen-Aliassen und eingegrenzten Regeln erlauben

Diese Anleitungen zeigen reale MCP-Tool-Nutzungsmuster und erläutern die Sicherheitsüberlegungen hinter jedem Ansatz.

Mitwirken

Siehe CONTRIBUTING.md für detaillierte Richtlinien. Kernpunkte:

1. Alle Tests müssen gemockte API-Antworten verwenden — niemals eine echte OPNsense-Instanz verbinden

2. Keine überlappenden Tools — jedes Tool muss einen eindeutigen Zweck haben

3. Klare Docstrings schreiben — sie sind die einzige Orientierung der KI für die Tool-Auswahl

4. Strukturierte Daten (Dictionaries) zurückgeben, keine formatierten Strings

5. Vor dem Einreichen make validate ausführen

Lizenz

MIT