OPNsense Guard

Name: OPNsense Guard
Author: d3ltasecurity

by d3ltasecurityversion 0.1.1i★ –iRuns on your computer

Registry nameio.github.d3ltasecurity/opnsense-guard-mcp

Install

Overview

Description from the maker (original English)

Safety-first OPNsense firewall MCP: read-only by default, planned and auto-reverting writes.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiVery new↓ 40/wk · ★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Cybersecurity
You need to fill in: OPNSENSE_URL, OPNSENSE_API_KEY, OPNSENSE_API_SECRET

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: OPNSENSE_URL, OPNSENSE_API_KEY, OPNSENSE_API_SECRET, OPNSENSE_CA_BUNDLE

Values marked secret are keys to your account. Never share them or paste them into a chat.

You need

PyPIPython’s uv installed (for the uvx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "opnsense-guard": {
      "command": "uvx",
      "args": [
        "opnsense-guard-mcp"
      ],
      "env": {
        "OPNSENSE_URL": "your-value",
        "OPNSENSE_API_KEY": "your-value",
        "OPNSENSE_API_SECRET": "your-value",
        "OPNSENSE_CA_BUNDLE": "your-value"
      }
    }
  }
}

Run this in your terminal

claude mcp add opnsense-guard --env OPNSENSE_URL=your-value --env OPNSENSE_API_KEY=your-value --env OPNSENSE_API_SECRET=your-value --env OPNSENSE_CA_BUNDLE=your-value -- uvx opnsense-guard-mcp

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "opnsense-guard": {
      "command": "uvx",
      "args": [
        "opnsense-guard-mcp"
      ],
      "env": {
        "OPNSENSE_URL": "your-value",
        "OPNSENSE_API_KEY": "your-value",
        "OPNSENSE_API_SECRET": "your-value",
        "OPNSENSE_CA_BUNDLE": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "opnsense-guard": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "opnsense-guard-mcp"
      ],
      "env": {
        "OPNSENSE_URL": "your-value",
        "OPNSENSE_API_KEY": "your-value",
        "OPNSENSE_API_SECRET": "your-value",
        "OPNSENSE_CA_BUNDLE": "your-value"
      }
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

OPNSENSE_URL required env
Firewall base URL, e.g. https://firewall.example.internal
OPNSENSE_API_KEY secret required env
API key of a least-privilege read user
OPNSENSE_API_SECRET secret required env
API secret of the read user
OPNSENSE_CA_BUNDLE env
CA file for a self-signed firewall certificate

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 9, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account d3ltasecurity, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Cybersecurityi

More stars than 0% of the other 1003 servers in this category
Published to the registry more recently than 75% of the other 1003 servers in this category
Basic checks equal to or better than 100% of the other 1003 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is OPNsense Guard safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: OPNSENSE_URL, OPNSENSE_API_KEY, OPNSENSE_API_SECRET

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.1.1) reached the registry 13 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Python (uv) on your computer.

What can I use instead?

In the same category: SUNGLASSES, KillerSkills, Draugr

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

SUNGLASSES

Input firewall for AI agents: scan text and files before they're read. Local, no network by default.

by sunglasses-devEarly↓ 549/wkUpdated today

Runs on your computer

Install

KillerSkills

Security verdicts for agent skills and MCP servers, from sandbox runs, before you install them.

by cyligence-karimGrowing↓ 3.1K/wkUpdated today

Runs on your computer

Install

Draugr

Security scanning for AI agents: SAST, SCA, secrets, IaC, DAST, ranked by real risk.

by draugr-devVery newUpdated today

Runs on your computer✓ draugr.dev

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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

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`, 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.

Install:

   pipx install opnsense-guard-mcp

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

Check the config (does not contact the firewall):

   opnsense-guard-mcp --check

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

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.

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

Point the client at https:// :8848/mcp with header Authorization: Bearer .

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:

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 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.
The change is pending: it is reverted automatically after confirm_timeout_s (default 60 s) unless change_confirm is called.
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.

OPNsense Guard

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Cybersecurityi

Common questions

Alternatives

SUNGLASSES

KillerSkills

Draugr

README from the maker

opnsense-guard-mcp

What makes it different

Quick start (read-only)

HTTP mode (shared server)

Running in Docker

stdio, for a local MCP client

HTTP: create a token, then serve (put the TLS files in the volume or mount them)

Policy and planning

Applying changes

Audit log

Tools (read-only)

Development

Security

Licence