Skip to main content
Glama
opnsense-guard-mcp

opnsense-guard-mcp

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 (audit verify detects edits); syslog planned

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)

  1. 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, planning

    Firewall: Aliases (view-only)

    firewall_aliases, planning

    Status: Interfaces

    interfaces

    Status: Services

    service_list

    Diagnostics: ARP Table

    arp_table

    Diagnostics: Routing tables

    routing_table

    Diagnostics: Show States

    firewall_states

    Diagnostics: Logs: Firewall: Live View

    firewall_log

    Diagnostics: Logs: System

    system_log

    Lobby: Dashboard

    system_information, system_resources, health probe

    Services: Intrusion Detection

    suricata_*

    Services: DHCP: Kea(v4) / Services: Dnsmasq DNS/DHCP: Settings / Status: DHCP leases (ISC)

    dhcp_leases: only the one you use

    System: 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.

  2. Install:

    pipx install opnsense-guard-mcp
  3. Configure (copy .env.example to .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=false
  4. Check the config (does not contact the firewall):

    opnsense-guard-mcp --check
  5. Add 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=true only behind a TLS proxy).

  1. Create a token per client. It is printed once; only its SHA-256 is stored:

    opnsense-guard-mcp token new --name laptop --scope read

    token list shows names and scopes; token revoke --name laptop takes effect on the next request, no restart needed.

  2. 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-mcp
  3. Point the client at https://<host>:8848/mcp with header Authorization: Bearer <token>.

Variable

Default

Purpose

MCP_HOST / MCP_PORT

127.0.0.1 / 8848

listen address

OPNSENSE_GUARD_TOKENS_FILE

./tokens.json

token hashes

MCP_TLS_CERT / MCP_TLS_KEY

–

serve HTTPS

MCP_TLS_CLIENT_CA

–

require client certificates (mTLS)

MCP_ALLOWED_HOSTS

localhost/127.0.0.1/MCP_HOST on the port

accepted Host headers (DNS-rebinding guard)

MCP_ALLOWED_ORIGINS

none

browser origins allowed; any other Origin is refused

MCP_RATE_LIMIT_PER_MIN

120

requests per token per minute

MCP_ALLOW_PLAINTEXT

false

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-mcp

Mount 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 on

Built-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:

  1. rule_plan / alias_plan → diff + plan_id (changes nothing).

  2. 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 with user_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.

  3. The change is pending: it is reverted automatically after confirm_timeout_s (default 60 s) unless change_confirm is called.

  4. change_rollback undoes a pending or confirmed change. A revert never overwrites an object someone else edited meanwhile (status conflict).

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=true is 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 20

Credentials 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 && pytest

Security

See SECURITY.md. Please report vulnerabilities privately.

Licence

MIT. See LICENSE.

Available Tools

21 tools
arp_tableA
Read-onlyIdempotent

ARP table: IP to MAC mappings currently known to the firewall.

Inputs: no named parameters.

dhcp_leasesA
Read-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_aliasesB
Read-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_logB
Read-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_getA
Read-onlyIdempotent

One filter rule by UUID, with all fields.

Args: uuid: rule UUID as shown by firewall_rules.

Inputs: uuid (required).

firewall_rulesA
Read-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_statesB
Read-onlyIdempotent

Active connection state table.

Args: limit: number of states to return (1-1000). search: optional filter on address or port.

Inputs: limit, search.

interfacesA
Read-onlyIdempotent

All network interfaces with status, addresses, and link state.

Inputs: no named parameters.

policy_showA
Read-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_checkA
Read-onlyIdempotent

Health snapshot: system, services, IDS state.

Flags security-relevant services that are installed but not running.

Inputs: no named parameters. Returns: object

raw_getB
Read-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_tableC
Read-onlyIdempotent

The firewall's active routing table.

Inputs: no named parameters.

security_auditA
Read-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_listA
Read-onlyIdempotent

All services OPNsense knows about and whether each is running.

Inputs: no named parameters.

suricata_alert_statusA
Read-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_settingsB
Read-onlyIdempotent

Suricata configuration: enabled, IPS mode, interfaces, active rulesets.

Inputs: no named parameters.

suricata_statusB
Read-onlyIdempotent

Whether the Suricata IDS/IPS service is running, stopped, or disabled.

Inputs: no named parameters.

system_informationB
Read-onlyIdempotent

Hostname, uptime, load, and general system information.

Inputs: no named parameters.

system_logB
Read-onlyIdempotent

Recent entries from the OPNsense system log.

Args: limit: number of lines to return (1-1000).

Inputs: limit.

system_resourcesB
Read-onlyIdempotent

Memory, swap, and disk utilisation of the firewall itself.

Inputs: no named parameters.

system_statusA
Read-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

    B3.4/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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'.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -