opnsense-guard-mcp
This MCP server provides read-only visibility, diagnostics, and security auditing for an OPNsense firewall.
Inspect system firmware/update status, host information, uptime/load, resources, and services.
Run a health/posture check that flags installed-but-not-running security services.
Check Suricata IDS/IPS status, settings, and alert-file liveness.
Review firewall rules, individual rule details, aliases, recent firewall logs, and active connection states.
View interfaces, ARP table, routing table, and DHCP leases across Kea, ISC, and dnsmasq.
Read recent OPNsense system logs.
Fetch any allowlisted OPNsense API path with
raw_get, under read-only constraints.Show the server's policy limits before planning changes.
Perform a quick security audit for risky rules and IDS issues.
All listed tools are marked read-only, idempotent, and non-destructive.
Provides a safety-first MCP server for OPNsense firewalls, with read-only tools for firewall rules and aliases, interfaces, services, ARP and routing tables, firewall states and logs, system information/resources, Suricata status, and DHCP leases. It also supports policy-checked planning and applying of firewall rule and alias changes, including diffs, human approval, verification, automatic revert, rollback, and a hash-chained audit log.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@opnsense-guard-mcp show me the active firewall rules on WAN and recent blocked traffic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
opnsense-guard-mcp
A safety-first MCP server for OPNsense 26.7+.
Read-only by default. Every write is planned, policy-checked, logged, and auto-reverted unless you confirm it.
Status: alpha. Tested against a live OPNsense 26.7.4 with least-privilege API users: read tools, policy file, change planning with diffs, applying changes with verification and automatic revert, crash recovery, and a hash-chained audit log, over stdio or authenticated HTTPS. See DESIGN.md.
Not affiliated with Deciso B.V. "OPNsense" is a trademark of Deciso B.V.
What makes it different
opnsense-guard-mcp | |
Default mode | read-only |
Read path | GET, plus POST to exactly two search endpoints (states, rules) with a fixed three-field body; path allowlist, verb denylist, traversal/encoding rejected, redirects not followed |
Writes | separate API user, exact endpoint allowlist, plan → policy check → human approval → apply → verify → auto-revert unless confirmed |
Rollback on 26.7+ | own object-level snapshots + revert (the savepoint API is gone in 26.7); survives restarts |
Guardrails | allowlist policy file: interfaces, networks, rule limits, anti-lockout |
Audit | hash-chained JSONL ( |
Transport | stdio, or Streamable HTTP that always needs a bearer token; optional TLS / mTLS |
Dangerous tools | none exist: no reboot, firmware, service control, SSH or XML edits |
Related MCP server: OPNsense MCP Server
Quick start (read-only)
In OPNsense (System → Access → Users), create a user with a scrambled password, no group (not
admins) and these privileges, then create an API key for it. Skip any that aren't installed; the matching tool just reports "forbidden".Privilege
Used by
Firewall: Rules [new]
firewall_rules,firewall_rule_get, planningFirewall: Aliases (view-only)
firewall_aliases, planningStatus: Interfaces
interfacesStatus: Services
service_listDiagnostics: ARP Table
arp_tableDiagnostics: Routing tables
routing_tableDiagnostics: Show States
firewall_statesDiagnostics: Logs: Firewall: Live View
firewall_logDiagnostics: Logs: System
system_logLobby: Dashboard
system_information,system_resources, health probeServices: Intrusion Detection
suricata_*Services: DHCP: Kea(v4) / Services: Dnsmasq DNS/DHCP: Settings / Status: DHCP leases (ISC)
dhcp_leases: only the one you useSystem: Firmware (optional)
system_status. It also allows installing updates, so leave it out unless you need it.Most OPNsense privileges are not view-only (Firewall: Aliases is an exception): several of these also allow edits through the API. The server only sends GET requests with this key, except a search POST to two exact endpoints (
diagnostics/firewall/query_states,firewall/filter/searchRule) with a body it builds itself (current,rowCount,searchPhrase); OPNsense answers those lists properly only over POST. Still keep the list short: the privileges are what OPNsense itself enforces.Install:
pipx install opnsense-guard-mcpConfigure (copy
.env.exampleto.env, or set env vars):OPNSENSE_URL=https://firewall.example.internal OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... OPNSENSE_CA_BUNDLE=/path/to/firewall-ca.pem # or OPNSENSE_VERIFY_SSL=falseCheck the config (does not contact the firewall):
opnsense-guard-mcp --checkAdd to your MCP client, e.g. Claude Code:
claude mcp add opnsense -- opnsense-guard-mcp --env-file /path/to/.env
HTTP mode (shared server)
HTTP never runs without authentication. The server refuses to start if:
there are no tokens, or
it binds to a non-loopback address without TLS (override with
MCP_ALLOW_PLAINTEXT=trueonly behind a TLS proxy).
Create a token per client. It is printed once; only its SHA-256 is stored:
opnsense-guard-mcp token new --name laptop --scope readtoken listshows names and scopes;token revoke --name laptoptakes effect on the next request, no restart needed.Start the server:
MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8848 \ MCP_TLS_CERT=server.pem MCP_TLS_KEY=server.key \ opnsense-guard-mcpPoint the client at
https://<host>:8848/mcpwith headerAuthorization: Bearer <token>.
Variable | Default | Purpose |
|
| listen address |
|
| token hashes |
| – | serve HTTPS |
| – | require client certificates (mTLS) |
|
| accepted |
| none | browser origins allowed; any other |
|
| requests per token per minute |
|
| allow plain HTTP on a non-loopback address |
Repeated failed logins from one IP (10 a minute) are throttled with HTTP 429.
Claude Code and a private CA: Claude Code (Node) ignores the Windows/macOS
certificate store for MCP servers. Point NODE_EXTRA_CA_CERTS at your CA file
in the env block of ~/.claude/settings.json, then fully quit and reopen
Claude, or the connection fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE.
Running in Docker
The image runs as a non-root user and keeps its audit log, change journal and
tokens in /data.
docker build -t opnsense-guard-mcp .
# stdio, for a local MCP client
docker run -i --rm --env-file .env -v guard-data:/data opnsense-guard-mcp
# HTTP: create a token, then serve (put the TLS files in the volume or mount them)
docker run --rm -v guard-data:/data opnsense-guard-mcp token new --name laptop --scope read
docker run -d --name opnsense-guard --env-file .env -v guard-data:/data -p 8848:8848 \
-e MCP_TRANSPORT=http -e MCP_HOST=0.0.0.0 -e MCP_ALLOWED_HOSTS=mcp.example.internal:8848 \
-e MCP_TLS_CERT=/data/tls/server.pem -e MCP_TLS_KEY=/data/tls/server.key \
opnsense-guard-mcpMount a policy file and set OPNSENSE_GUARD_POLICY to enable writes. Stop the
container with docker stop (not kill) so unconfirmed changes are reverted.
Policy and planning
Without a policy.yaml the server is read-only. To enable planning, copy
policy.example.yaml to policy.yaml (or point
OPNSENSE_GUARD_POLICY at it) and edit it. Unknown keys are an error.
Planning tools (rule_plan, alias_plan) read the current state, apply every
policy check, and return a diff plus the reasons for any refusal. They never
change the firewall. Example result for a refused rule:
+ [wan] pass in inet any from any to any '[mcp]'
interface 'wan' is not in the allowed interfaces
any -> any pass rules are forbidden
inbound pass rules on WAN are forbidden
every rule written by this server must have logging onBuilt-in guardrails: only listed interfaces/actions/directions; every IP inside
allow_networks; no any→any pass, WAN inbound pass, floating rules or rules
without logging; edit only rules tagged [mcp] (unless only_modify_own: false);
anti-lockout (no block rule that matches this server's own IP, and only new
pass rules on the interface it reaches the API through). A new block or reject
rule there is allowed when the same plan adds a pass rule with a lower
sequence that provably lets every MCP host reach the API (source covers the
host IP, destination any/(self)/the API IP, TCP, port covers the API port);
both rules need a sequence.
Applying changes
Change tools appear only when both the policy is in write mode and a second, write-capable API user is configured:
OPNSENSE_WRITE_API_KEY=... # a different OPNsense user than the read one
OPNSENSE_WRITE_API_SECRET=...Give that user exactly two privileges: Firewall: Rules [new] and
Firewall: Alias: Edit, no group. (Plain Firewall: Aliases is view-only:
it allows search/get but not addItem/setItem/delItem/reconfigure.) Over HTTP, the
change tools need a token with --scope write.
The flow:
rule_plan/alias_plan→ diff +plan_id(changes nothing).change_apply(plan_id)→ asks the human to approve the diff (MCP elicitation where the client supports it; otherwise the tool returns the diff and must be called again withuser_confirmed=true). Then it re-reads the firewall (refuses if anything drifted since planning), stores the before-state, writes, applies, reads everything back to verify, and checks the API is still reachable. Any failure → everything is reverted.The change is pending: it is reverted automatically after
confirm_timeout_s(default 60 s) unlesschange_confirmis called.change_rollbackundoes a pending or confirmed change. A revert never overwrites an object someone else edited meanwhile (statusconflict).
Unconfirmed changes are also reverted when the server stops and, after a
crash, when it starts again. Only one change can be open at a time, and
max_changes_per_hour is enforced.
Limits, stated plainly
The revert timer runs on the MCP host. If a change cuts that host off from the firewall API, the revert cannot reach it. The anti-lockout policy and the health probe right after apply exist to prevent and catch this, but they are not the same as the firewall-side savepoint older OPNsense versions had.
Without elicitation,
user_confirmed=trueis the model's word that the user agreed. The audit log records which method was used.
Audit log
Every plan (allowed or refused) and server start is written to
$OPNSENSE_GUARD_DATA_DIR/audit.jsonl (default ./data). Each line holds the
hash of the previous one, so edits, deletions and reordering are detectable:
opnsense-guard-mcp audit verify
opnsense-guard-mcp audit tail -n 20Credentials are never written to it.
Tools (read-only)
system_status, system_information, system_resources, service_list,
posture_check, suricata_status, suricata_settings, suricata_alert_status,
firewall_rules, firewall_rule_get, firewall_aliases, firewall_log,
firewall_states, system_log, interfaces, arp_table, routing_table,
dhcp_leases, raw_get, policy_show, security_audit.
In write mode also: rule_plan, alias_plan, plan_get, audit_tail.
With write credentials also: change_apply, change_confirm, change_rollback,
change_list, change_get.
firewall_rules returns one line per rule (50 by default) so a full ruleset
fits in a chat; pass detail=true for the raw OPNsense rows, or use
firewall_rule_get for one rule.
Over HTTP, a read token still sees the change tools in the tool list, but
calling one is refused (needs a token with scope 'write').
Development
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
ruff check . && mypy && pytestSecurity
See SECURITY.md. Please report vulnerabilities privately.
Licence
MIT. See LICENSE.
Available Tools
21 toolsarp_tableARead-onlyIdempotent
ARP table: IP to MAC mappings currently known to the firewall.
Inputs: no named parameters.
dhcp_leasesARead-onlyIdempotent
Current DHCP leases across all backends (Kea, ISC dhcpd, dnsmasq).
Queries all three and reports which backend actually holds leases.
Inputs: no named parameters. Returns: object
firewall_aliasesBRead-onlyIdempotent
Firewall aliases and their contents.
Args: search: optional text filter on alias name or description. limit: maximum aliases to return (1-1000).
Inputs: limit, search.
firewall_logBRead-onlyIdempotent
Recent firewall log entries (pass/block decisions).
Args: limit: number of log lines to return (1-1000). search: optional filter phrase (IP, port, interface, action).
Inputs: limit, search.
firewall_rule_getARead-onlyIdempotent
One filter rule by UUID, with all fields.
Args: uuid: rule UUID as shown by firewall_rules.
Inputs: uuid (required).
firewall_rulesARead-onlyIdempotent
The firewall filter ruleset, one line per rule.
Use firewall_rule_get for every field of one rule.
Args: search: optional text filter (interface, description, address). limit: maximum rules to return (1-1000). detail: return the full OPNsense rows instead of one-line summaries.
Inputs: limit, detail, search.
firewall_statesBRead-onlyIdempotent
Active connection state table.
Args: limit: number of states to return (1-1000). search: optional filter on address or port.
Inputs: limit, search.
interfacesARead-onlyIdempotent
All network interfaces with status, addresses, and link state.
Inputs: no named parameters.
policy_showARead-onlyIdempotent
What this server is allowed to change: mode, interfaces, networks, limits.
Read this before planning a change so you know the limits.
Inputs: no named parameters. Returns: object
posture_checkARead-onlyIdempotent
Health snapshot: system, services, IDS state.
Flags security-relevant services that are installed but not running.
Inputs: no named parameters. Returns: object
raw_getBRead-onlyIdempotent
GET any allowlisted OPNsense API path.
The same read-only rules apply (prefix allowlist, verb denylist, no traversal), so this cannot change firewall state.
Args: path: API path beginning with /api/, e.g. /api/core/firmware/info
Inputs: path (required).
routing_tableCRead-onlyIdempotent
The firewall's active routing table.
Inputs: no named parameters.
security_auditARead-onlyIdempotent
Quick security review of the ruleset and IDS.
Flags any->any pass rules, inbound pass on WAN, pass rules without logging, and an IDS that is not running.
Inputs: no named parameters. Returns: object
service_listARead-onlyIdempotent
All services OPNsense knows about and whether each is running.
Inputs: no named parameters.
suricata_alert_statusARead-onlyIdempotent
Whether Suricata is producing alerts, from its eve.json file metadata.
OPNsense only serves alert rows over POST (queryAlerts), which a read-only server must not call. This reports liveness instead: the log file's size and last-modified time. Query alerts in your SIEM.
Inputs: no named parameters. Returns: object
suricata_settingsBRead-onlyIdempotent
Suricata configuration: enabled, IPS mode, interfaces, active rulesets.
Inputs: no named parameters.
suricata_statusBRead-onlyIdempotent
Whether the Suricata IDS/IPS service is running, stopped, or disabled.
Inputs: no named parameters.
system_informationBRead-onlyIdempotent
Hostname, uptime, load, and general system information.
Inputs: no named parameters.
system_logBRead-onlyIdempotent
Recent entries from the OPNsense system log.
Args: limit: number of lines to return (1-1000).
Inputs: limit.
system_resourcesBRead-onlyIdempotent
Memory, swap, and disk utilisation of the firewall itself.
Inputs: no named parameters.
system_statusARead-onlyIdempotent
OPNsense firmware version and pending updates (needs the System: Firmware privilege).
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools target clearly distinct resources (suricata_status/settings/alert_status, firewall_rules/rule_get/log/states are well separated). Some softer overlap exists between posture_check and security_audit (both health/security snapshots) and among system_status/system_information/system_resources, but descriptions give enough signals to choose correctly.
All names are snake_case with predictable domain prefixes (system_, service_, suricata_, firewall_, dhcp_) and readable verb_noun forms for actions (posture_check, policy_show, security_audit). A few bare nouns (interfaces, arp_table, routing_table) deviate slightly but remain clear.
21 tools is on the heavy side for a read-only guard server; the suricata and system clusters each add several closely related tools. Every tool does earn a purpose, but the surface sits at the borderline of 'feels heavy'.
For a deliberately read-only server it covers system, services, IDS, firewall rules/aliases/logs/states, logs, interfaces, ARP, routing and DHCP well, with raw_get as an escape hatch for gaps. The notable gap is that policy_show references allowed changes but no mutation tools exist, which may confuse agents expecting lifecycle operations.
Maintenance
Related MCP Connectors
Checks AI agent actions before they run. Signed, RFC 3161 timestamped evidence for audits.
Supervised API-write gateway for AI agents with policy, human approval and execution receipts.
Runtime AI governance: decision gates, human approval, hash-chained audit, compliance mapping.
Tamper-evident SHA-256 hash-chained decision notary for EU AI Act, NIST AI RMF & SOC2.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables natural language interaction and management of pfSense firewalls through Claude and other GenAI applications using the Model Context Protocol. It provides advanced tools for firewall rule configuration, interface management, and intelligent log analysis via a REST API integration.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language management of OPNsense firewalls through AI clients, providing tools for firewall rules, system health, VPN monitoring, and more.AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to manage OPNsense firewall, interfaces, DHCP, DNS, routes, and services via natural language through 42 MCP tools.1MIT
- FlicenseNot gradedqualityAmaintenanceEnables natural-language management of pfSense firewalls through MCP clients, covering firewall rules, VPNs, DNS, DHCP, diagnostics, configuration backup, and safety guardrails for destructive changes. It supports wire-format-verified operations across major pfSense subsystems with confirmation, rate limits, and rollback guidance.-