opnsense-mcp

An MCP server for the OPNsense firewall REST API. It gives an LLM structured, paginated access to rules, aliases, live pf state, logs, interfaces, DNS and VPN status — and keeps every write behind an explicit gate.

Built for a firewall at https://192.168.1.1, but the address is configuration, not a constant.

Requirements

• Python 3.11+

• Network reachability to the OPNsense WebGUI port

• An OPNsense API key pair

Related MCP server: coreyhines/opnsense-mcp

Install

git clone <this repo> opnsense-mcp && cd opnsense-mcp
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

Verify the package loads before wiring it into a client:

opnsense-mcp --version

Create an API key

1. In the OPNsense GUI: System → Access → Users

2. Edit the user the server should act as (create a dedicated one — see Least privilege)

3. Under API keys, press +. A apikey.txt downloads containing key and secret. It is shown once.

TLS

OPNsense ships a self-signed WebGUI certificate, so plain verification fails out of the box. Two options, in order of preference:

Pin the firewall's certificate. Export it from System → Trust → Certificates and point at the PEM file:

export OPNSENSE_CA_BUNDLE=/etc/ssl/opnsense.pem

Disable verification. Works, but the API key travels over a path anyone in the middle can read. Acceptable on a trusted management segment; not otherwise:

export OPNSENSE_VERIFY_TLS=false

Configuration

All configuration is environment-only. Credentials never appear in tool arguments, so they cannot end up in a conversation transcript.

.env.example has the same set with commentary.

On startup the server prints its resolved configuration to stderr (never stdout — stdio transport uses stdout for the protocol itself) and warns about missing credentials, disabled TLS verification, and enabled writes.

Wiring it into a client

Hand it to an agent: docs/AGENT-SETUP-PROMPT.md is a paste-ready prompt that does the whole Windows setup with verification gates.

Windows: see docs/WINDOWS.md — Claude Desktop does not inherit your shell PATH, which breaks the bundle's uv lookup.

Claude Desktop: install opnsense-mcp-0.1.1.mcpb via Settings -> Extensions. Credentials go to your OS keychain, not a config file. Build it with cp -r opnsense_mcp mcpb/ && npx @anthropic-ai/mcpb pack mcpb.

Full walkthrough for every surface, including why claude.ai remote connectors are the wrong choice here: docs/CONNECTING.md.

Use scripts/opnsense-mcp-env.sh rather than putting the API secret directly in client config — both Claude Code and Claude Desktop store those values in plaintext.

stdio (Claude Desktop, Claude Code)

{
  "mcpServers": {
    "opnsense": {
      "command": "/path/to/opnsense-mcp/.venv/bin/opnsense-mcp",
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "…",
        "OPNSENSE_API_SECRET": "…",
        "OPNSENSE_CA_BUNDLE": "/etc/ssl/opnsense.pem"
      }
    }
  }
}

Streamable HTTP (OpenWebUI and other remote clients)

opnsense-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

Runs stateless with JSON responses, which is the simpler thing to put behind a proxy. It binds to loopback by default and warns loudly if you bind wider: the server itself has no authentication, so anything that can reach the port can drive your firewall API. For remote access, terminate auth in a reverse proxy in front of it, or reach it over Tailscale/WireGuard rather than exposing the port.

Tools

Twenty-six tools, all prefixed opnsense_. Every collection tool takes limit, offset and response_format (markdown for reading, json for chaining values into a follow-up call) and returns total / count / has_more / next_offset.

System

Network

Firewall rules

Aliases

Live diagnostics

DNS and VPN

Escape hatch

Command names in the published API reference are snake_case; URLs use camelCase. get_interface_names → getInterfaceNames.

Resources

• opnsense://interfaces — the interface map as JSON

• opnsense://aliases — all configured aliases

Safety model

Three layers, because a firewall is the one box where a bad automated change can remove your ability to fix it.

1. Writes fail closed. With OPNSENSE_ALLOW_WRITE unset, every write tool returns an explanation of how to enable it and issues no HTTP request at all. There is a test asserting zero requests reach the firewall in that state.

2. Rule changes go through savepoints. OPNsense's savepoint mechanism applies a change with a 60-second dead-man's switch: if nobody confirms, the firewall reverts itself. opnsense_apply_firewall_changes wraps it and each response states the next step:

1. mode='savepoint'                        → returns a revision
2. make changes                            → e.g. toggle a rule
3. mode='apply', revision=<from step 1>    → 60s auto-revert armed
4. verify you can still reach the firewall
5. mode='cancel_rollback', same revision   → change becomes permanent

Skipping step 5 is safe. Skipping step 1 is not: an apply with no savepoint cannot be undone remotely.

3. Some endpoints are refused outright, regardless of the write flag: reboot, halt, factory reset, config revert, snapshot activation, user account changes. Those need a human who can reach the console. opnsense_kill_states additionally rejects wildcard filters, so flushing the entire state table is not reachable by accident.

Note the asymmetry that is not a bug: alias edits and state kills are live immediately with no savepoint, because that is how OPNsense implements them. The tool descriptions say so. Blocking an address by adding it to an alias is the fast path; it is also the one with no undo.

Least privilege

Create a dedicated user for the API key rather than reusing an admin account. Grant only the pages the tools you actually want need, then check the result under System → Access → Users → (user) → Effective Privileges.

A useful signal when tuning this: a 403 on one endpoint while other calls succeed always means a missing privilege, never bad credentials. The error messages say this explicitly so an agent stops trying to re-authenticate.

Troubleshooting

Tests

pip install -e ".[dev]"
pytest -q

Twenty-two tests run against mocked HTTP (respx) — no firewall required. They cover the parts that are expensive to debug live: grid pagination arithmetic including the unaligned-offset page stitch, the write gate, endpoint refusal, path-traversal rejection, error translation, and graceful degradation when one section of a multi-endpoint call fails.

Known gaps

Endpoint paths taken from the published OPNsense API reference are solid. The following were inferred and should be confirmed on first run against a live firewall — each has a specific reason it could differ:

• kea/leases4/search — the reference documents only the abstract leases controller, so the concrete v4 controller name is an inference

• dhcpv4/leases/searchLease (ISC fallback) and openvpn/service/searchSessions

• Request body key shapes: alias_util add/delete (address), killStates (filter), findReferences (alias)

• diagnostics/firewall/log server-side filter parameters — rather than guess, the tool fetches a window and filters locally, which is why it reports window_size and warns when a narrow filter over a busy firewall returns nothing

Two tools already degrade rather than fail: DHCP leases falls back Kea → ISC, and alias references falls back from the API endpoint to a filter-rule scan, labelling its own reduced coverage in the output.

Not yet wrapped, reachable via opnsense_api_request: NAT rules, traffic shaping, IDS/Suricata, captive portal, certificates, CrowdSec and other plugin endpoints.

See evaluation.xml for the evaluation harness and what needs filling in.