Skip to main content
Glama

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: OPNsense MCP Server

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.

Variable

Default

Purpose

OPNSENSE_URL

https://192.168.1.1

Base URL including scheme

OPNSENSE_API_KEY

(unset)

API key

OPNSENSE_API_SECRET

(unset)

API secret

OPNSENSE_CA_BUNDLE

(unset)

Path to a PEM file; takes precedence over VERIFY_TLS

OPNSENSE_VERIFY_TLS

true

Set false to skip verification

OPNSENSE_TIMEOUT

30

Request timeout in seconds

OPNSENSE_ALLOW_WRITE

false

Master switch for every write tool

.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

Tool

Notes

opnsense_get_system_status

Version, uptime, load, memory, temperature, disk. Sections whose endpoint is missing are omitted rather than failing the call

opnsense_get_firmware_status

Pending updates and installed vs latest version

opnsense_list_services

Core and plugin services with running state

opnsense_control_service

write — start / stop / restart

Network

Tool

Notes

opnsense_list_interfaces

Maps config names (lan, opt2) to device names (igb0, vlan0.30). Call this first whenever a question spans rules and diagnostics

opnsense_get_interface_statistics

Cumulative counters, not rates — call twice and difference

opnsense_search_neighbors

ARP and NDP tables, family = ipv4 / ipv6 / both

opnsense_get_routes

Active routing table

opnsense_list_dhcp_leases

Kea with automatic fallback to legacy ISC

Firewall rules

Tool

Notes

opnsense_search_firewall_rules

Rules in evaluation order with action, interface, source, destination

opnsense_get_firewall_rule

Full record by UUID; enum fields flattened from OPNsense's {value, selected} form

opnsense_get_rule_statistics

Per-rule evaluations / packets / bytes / states. unused_only=true finds dead rules — but counters reset on every apply

opnsense_toggle_firewall_rule

write — stages only; nothing is live until applied

opnsense_apply_firewall_changes

write — savepoint / apply / cancel_rollback / revert

Aliases

Tool

Notes

opnsense_search_aliases

Alias configuration

opnsense_get_alias_contents

What the pf table actually holds — the two diverge when a URL table or GeoIP feed fails to refresh

opnsense_find_alias_references

What breaks if this alias changes

opnsense_update_alias_entries

write — add/remove entries; live immediately, per-entry outcomes reported

Live diagnostics

Tool

Notes

opnsense_get_firewall_log

Recent entries filtered by verdict / interface / address / port / protocol

opnsense_query_firewall_states

pf state table — what is happening now

opnsense_get_pf_statistics

State table usage, memory limits, drop counters

opnsense_kill_states

write — drop states matching an address; wildcards rejected

DNS and VPN

Tool

Notes

opnsense_get_dns_overview

Unbound service state, blocklist status, cache counters

opnsense_search_dns_queries

Recent lookups per client; needs Reporting enabled under Services → Unbound DNS

opnsense_get_vpn_status

WireGuard peers and OpenVPN sessions

Escape hatch

Tool

Notes

opnsense_api_request

Any endpoint. GET always allowed; POST needs OPNSENSE_ALLOW_WRITE and confirm=true. Use for NAT (firewall/source_nat, firewall/d_nat), traffic shaping, IDS, certificates, CrowdSec

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

Symptom

Cause

TLS verification failed

Self-signed WebGUI cert. Set OPNSENSE_CA_BUNDLE or OPNSENSE_VERIFY_TLS=false

HTTP 401/403 on everything

Wrong key/secret, or the key's user has no API access

HTTP 403 on one endpoint only

Missing ACL for that page. Check Effective Privileges

HTTP 404 on an endpoint

Plugin not installed, or this OPNsense release predates it

Returned HTML instead of JSON

OPNSENSE_URL points somewhere that is not the API

Read timeout

Large state tables and log queries are slow. Lower limit or raise OPNSENSE_TIMEOUT

Firewall log returns nothing

Only rules with logging enabled produce entries. Absence is not evidence of a block

DNS query search is empty

Reporting is off under Services → Unbound DNS → Reporting

Alias contents empty

An alias is only loaded into pf when an enabled rule references it

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.

Available Tools

26 tools
opnsense_api_requestA
Destructive

Call any OPNsense API endpoint directly. Use this only for endpoints the other tools do not cover.

The dedicated tools shape their output, handle pagination and explain their failures; this returns raw JSON. Reach for it when you need something outside their scope, for example NAT rules (firewall/source_nat, firewall/d_nat), traffic shaping, IDS/Suricata, captive portal, certificates, or plugin endpoints such as CrowdSec.

Endpoint naming: the published reference lists commands in snake_case but URLs use camelCase, so get_interface_names becomes getInterfaceNames and query_states becomes queryStates.

GET is always permitted. POST requires both OPNSENSE_ALLOW_WRITE=true and confirm=true. A small set of endpoints is refused outright regardless of settings: reboot, halt, factory reset, configuration revert, snapshot activation and user account changes. Those need a human who can reach the console if it goes wrong.

Args: params (ApiRequestInput): Validated input containing: - module (str): e.g. "firewall" - controller (str): e.g. "source_nat" - command (str): camelCase command, e.g. "searchRule" - method (str): "GET" or "POST" (default: "GET") - segments (list[str]): Extra path segments (default: []) - params (dict): Query parameters (default: {}) - body (dict): JSON body for POST (default: {}) - confirm (bool): Required true for POST (default: False) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: The endpoint's JSON response, pretty-printed. Responses longer than 20000 characters are truncated with a note; narrow the query rather than relying on the truncated tail.

Examples: - Use when: "List NAT port forwards" -> module="firewall", controller="source_nat", command="searchRule" - Use when: "What log filter fields exist?" -> module="diagnostics", controller="firewall", command="logFilters" - Don't use when: A dedicated tool exists; it will give better-structured output

Error Handling: - Refuses forbidden endpoints with an explanation - Returns a write-disabled explanation for POST when writes are off - Returns a confirm-required message for POST without confirm=true

Inputs: params (required). Returns: result

opnsense_apply_firewall_changesA
Destructive

Activate staged firewall changes, with automatic rollback protection.

Requires OPNSENSE_ALLOW_WRITE=true. This wraps OPNsense's savepoint mechanism, which exists because a bad rule can lock you out of the firewall that hosts the API you would need to fix it.

The sequence, in order:

  1. mode='savepoint' -> returns a revision timestamp

  2. make changes -> e.g. opnsense_toggle_firewall_rule

  3. mode='apply' -> with revision=<from step 1>; the firewall will revert to that revision by itself in 60 seconds

  4. verify connectivity -> confirm the firewall is still reachable

  5. mode='cancel_rollback' -> with the same revision; makes the change permanent

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

mode='revert' rolls back to a revision immediately without waiting.

Args: params (ApplyChangesInput): Validated input containing: - mode (str): 'savepoint', 'apply', 'cancel_rollback' or 'revert' - revision (str): Revision timestamp, required for all modes except savepoint - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Text describing what happened and what to do next, or JSON: {"mode": str, "revision": str, "result": str, "next_step": str}

Error Handling: - Returns a write-disabled explanation when OPNSENSE_ALLOW_WRITE is not set - Returns a validation message when revision is missing for a mode that needs it

Inputs: params (required). Returns: result

opnsense_control_serviceA
Destructive

Start, stop or restart a service on the firewall.

Requires OPNSENSE_ALLOW_WRITE=true. Stopping a service is disruptive: stopping unbound breaks DNS for every client behind the firewall, and stopping a VPN service drops its tunnels. Confirm the intent before calling with action='stop'.

Args: params (ControlServiceInput): Validated input containing: - name (str): Service id, e.g. "unbound" - action (str): "start", "stop" or "restart" - service_id (str): Instance id for multi-instance services (default: "") - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Confirmation text, or JSON: {"result": str, "service": str, "action": str}

Error Handling: - Returns a write-disabled explanation when OPNSENSE_ALLOW_WRITE is not set - Returns a 403 privilege message when the API key cannot control services

Inputs: params (required). Returns: result

opnsense_find_alias_referencesA
Read-onlyIdempotent

Find where an alias is referenced, so you know what would break if it changed.

Tries the firewall's own reference lookup first. If that endpoint is unavailable on this release, falls back to scanning filter rules for the alias name and says so in the output, since that fallback covers filter rules only and not NAT rules or other aliases that nest this one.

Args: params (AliasReferencesInput): Validated input containing: - name (str): Alias name - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown list of referencing objects, or JSON with this schema: {"alias": str, "source": "api"|"rule_scan", "references": [...]}

Examples: - Use when: "Is this alias still used?" before deleting it - Use when: "What breaks if I empty this list?"

Inputs: params (required). Returns: result

opnsense_get_alias_contentsA
Read-onlyIdempotent

Get the addresses currently loaded in an alias's pf table.

This reads the live table, so it reflects resolved hostnames, downloaded URL table feeds and refreshed GeoIP sets. When a rule using an alias is not behaving as expected, comparing this against the alias configuration is usually the fastest way to find that a feed failed to refresh.

Args: params (AliasContentsInput): Validated input containing: - name (str): Alias name - limit (int): Max entries, 1-200 (default: 25) - offset (int): Entries to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "alias": str, "entries": [{"ip": str}] }

Error Handling: - Returns a not-loaded message when the alias exists but has no pf table, which happens when no enabled rule references it

Inputs: params (required). Returns: result

opnsense_get_dns_overviewA
Read-onlyIdempotent

Get the state of the Unbound DNS resolver: whether it is running, whether DNS blocklisting is active, and its cache and query counters.

Clients reporting "the internet is down" when routing is fine is almost always DNS. Check here before looking at firewall rules: a stopped resolver or an exhausted cache produces exactly that symptom with no blocks in the firewall log.

Args: params (DnsOverviewInput): Validated input containing: - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown summary, or JSON with this schema: { "service": {"status": str}, # "running" / "stopped" "blocklist_enabled": bool, "stats": {...} # cache hits/misses, query counts } Sections whose endpoint is unavailable are omitted.

Examples: - Use when: "Is DNS working?" or "Is the blocklist on?" - Don't use when: You want to see individual lookups (use opnsense_search_dns_queries)

Inputs: params (required). Returns: result

opnsense_get_firewall_logA
Read-only

Read recent firewall log entries and filter them by verdict, interface, address, port or protocol.

This is the primary tool for "why was this traffic blocked". Two caveats that change how you should read the results:

  • Only rules with logging enabled produce entries. Traffic silently dropped by the default deny rule appears as a block against the default rule label; traffic allowed by a rule with logging off produces nothing at all. Absence of a log entry is therefore not evidence that traffic was blocked.

  • Filtering is applied locally over the most recent entries this call retrieved, so a narrow filter over a busy firewall may return nothing simply because the matching packets are older than the window. Raise 'limit' before concluding there is no traffic.

Args: params (FirewallLogInput): Validated input containing: - action (str): "pass", "block" or "rdr" (default: "") - interface (str): Device name filter (default: "") - address (str): Substring match on source or destination (default: "") - port (str): Exact source or destination port (default: "") - protocol (str): Protocol name filter (default: "") - limit (int): Max entries to return, 1-200 (default: 25) - offset (int): Entries to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, # matching entries in the retrieved window "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "window_size": int, # raw entries examined "entries": [ {"timestamp": str, "action": str, "interface": str, "dir": str, "protoname": str, "src": str, "srcport": str, "dst": str, "dstport": str, "label": str, "rid": str} ] }

Examples: - Use when: "Why can't the IOT camera reach the internet?" -> address="192.168.30.57", action="block" - Use when: "What is being blocked on WAN right now?" -> interface="pppoe0", action="block" - Don't use when: You want established connections (use opnsense_query_firewall_states)

Inputs: params (required). Returns: result

opnsense_get_firewall_ruleA
Read-onlyIdempotent

Get every configured field of a single firewall rule by UUID.

The search tool returns a summary; this returns the full record including scheduling, state policy, logging, gateway assignment, categories and reply-to, which is what you need before changing or reproducing a rule.

Args: params (GetRuleInput): Validated input containing: - uuid (str): Rule UUID - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown field list, or JSON containing the full rule object. Enum fields are flattened from OPNsense's {"value": ..., "selected": 1} form to the selected value.

Error Handling: - Returns a not-found message when the UUID does not exist

Inputs: params (required). Returns: result

opnsense_get_firmware_statusA
Read-onlyIdempotent

Check for pending OPNsense updates and report the installed version and repository state.

Note that OPNsense caches its update check. If the result looks stale, the firmware/check endpoint (reachable via opnsense_api_request) forces a refresh. This tool never installs anything.

Args: params (FirmwareStatusInput): Validated input containing: - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown summary, or JSON with this schema: { "status": str, # "ok", "error", "none" "status_msg": str, # human-readable state, when present "product_version": str, # currently installed version "product_latest": str, # latest available version "upgrade_needs_reboot": str, # "1" when a reboot would be required "download_size": str, "updates": list # per-package update records }

Examples: - Use when: "Are there updates pending?" or "What's the latest OPNsense version?" - Don't use when: You want uptime or load (use opnsense_get_system_status)

Inputs: params (required). Returns: result

opnsense_get_interface_statisticsA
Read-onlyIdempotent

Get packet, byte, error and collision counters per interface.

These are cumulative counters since boot, not rates. To measure throughput, call twice and take the difference over the elapsed time. Rising error or collision counts on a physical NIC usually mean a duplex mismatch or a bad cable.

Args: params (InterfaceStatisticsInput): Validated input containing: - device (str): Device name to filter to, e.g. "igb0" (default: "" = all) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON mapping device name to a counter object: {"": {"packets in": int, "packets out": int, "bytes in": int, "bytes out": int, "errors in": int, "errors out": int, "collisions": int, ...}}

Examples: - Use when: "Is the WAN dropping packets?" -> device="pppoe0" - Don't use when: You want live per-connection traffic (use opnsense_query_firewall_states)

Inputs: params (required). Returns: result

opnsense_get_pf_statisticsA
Read-onlyIdempotent

Get packet filter engine statistics: state table usage, memory limits, counters and timeouts.

Read this when the firewall drops traffic under load rather than by policy. State table exhaustion and hitting a memory limit both show up here as non-zero counters, and neither produces a block entry in the firewall log, which is why load-related drops are so often misdiagnosed as rule problems.

Args: params (PfStatisticsInput): Validated input containing: - section (str): "memory", "timeouts", "interfaces" or "" for all - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown sections, or the raw JSON statistics object. Keys vary by OPNsense release; commonly present are current state count, state limit, searches, inserts, and per-reason drop counters.

Inputs: params (required). Returns: result

opnsense_get_routesA
Read-onlyIdempotent

Get the firewall's active routing table, including the default route and any policy or VPN routes.

Useful when traffic reaches the firewall but leaves the wrong way, or when checking that a VPN tunnel installed the routes it should have.

Args: params (GetRoutesInput): Validated input containing: - search (str): Filter on destination, gateway or interface (default: "") - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "routes": [ {"destination": str, "gateway": str, "netif": str, "flags": str, "proto": str, "expire": str} ] }

Examples: - Use when: "What's the default route?" -> search="default" - Use when: "Did the WireGuard tunnel add its routes?" -> search="wg"

Inputs: params (required). Returns: result

opnsense_get_rule_statisticsA
Read-onlyIdempotent

Get per-rule pf counters: how many times each rule was evaluated, and how many packets, bytes and states it accounted for.

This turns "which rules actually matter" into a data question. Counters reset every time the ruleset is reloaded, so a zero count means "not matched since the last apply", not "never matched". Confirm the ruleset has been stable for a while before concluding a rule is dead.

Args: params (RuleStatisticsInput): Validated input containing: - search (str): Filter on rule label or interface (default: "") - unused_only (bool): Only rules with zero evaluations (default: False) - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "rule_stats": [ {"label": str, "evaluations": int, "packets": int, "bytes": int, "states": int, "interface": str} ] }

Examples: - Use when: "Which rules are never hit?" -> unused_only=True - Use when: "How much traffic does the guest block rule see?" -> search="guest"

Inputs: params (required). Returns: result

opnsense_get_system_statusA
Read-onlyIdempotent

Get a health overview of the OPNsense firewall: version, uptime, load, memory, optional temperature sensors and optional disk usage.

Start here when asked how the firewall is doing, what version it runs, or whether it is under load. This does NOT report firmware updates - use opnsense_get_firmware_status for that.

Args: params (SystemStatusInput): Validated input containing: - include_temperature (bool): Include temperature sensors (default: True) - include_disk (bool): Include filesystem usage (default: True) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown summary, or JSON with this schema: { "system": {...}, # product name, versions, uptime, CPU model "resources": {...}, # load average, memory and swap usage "temperature": [...], # optional, per-sensor readings "disk": {...}, # optional, per-filesystem usage "status": {...} # pending notices and their severity } Sections whose endpoint is unavailable on this release are omitted.

Examples: - Use when: "Is the firewall healthy?" or "What OPNsense version am I on?" - Don't use when: You want pending updates (use opnsense_get_firmware_status) - Don't use when: You want per-interface throughput (use opnsense_get_interface_statistics)

Inputs: params (required). Returns: result

opnsense_get_vpn_statusA
Read-onlyIdempotent

Get the status of WireGuard peers and OpenVPN sessions, including last handshake times and transfer counters.

For WireGuard, last handshake is the field that matters: a configured peer with no recent handshake is not connected, no matter what the interface status says. WireGuard is connectionless, so there is no "down" state to observe directly.

Args: params (VpnStatusInput): Validated input containing: - kind (str): "wireguard", "openvpn" or "both" (default: "both") - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown sections per VPN type, or JSON with this schema: { "wireguard": [ {"name": str, "interface": str, "endpoint": str, "latest-handshake": str, "transfer-rx": str, "transfer-tx": str, "allowed-ips": str} ], "openvpn": [ {"common_name": str, "real_address": str, "virtual_address": str, "bytes_received": str, "bytes_sent": str, "connected_since": str} ] } A key is omitted when that VPN type is not configured or its endpoint is absent.

Examples: - Use when: "Is my phone connected over WireGuard?" -> kind="wireguard" - Use when: "Who is on the VPN right now?" -> kind="both"

Inputs: params (required). Returns: result

opnsense_kill_statesA
Destructive

Drop tracked connection states matching an address or subnet.

Requires OPNSENSE_ALLOW_WRITE=true. This takes effect immediately and cannot be undone: every matching connection is torn down, and clients see it as a dropped session. It does not change policy, so if a rule still permits the traffic the client will simply reconnect.

Legitimate uses are forcing a host back through a changed rule set, and cutting an active session from a compromised device. It is not a way to block a host; add the address to a blocked alias with opnsense_update_alias_entries for that.

A wildcard filter is rejected. Flushing the entire state table drops every connection through the firewall simultaneously, which is a decision for a human at a console.

Args: params (KillStatesInput): Validated input containing: - filter (str): Address or subnet whose states to drop (required) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Confirmation including how many states were dropped, or JSON: {"filter": str, "dropped": int, "result": str}

Error Handling: - Returns a write-disabled explanation when OPNSENSE_ALLOW_WRITE is not set - Rejects wildcard filters during input validation

Inputs: params (required). Returns: result

opnsense_list_dhcp_leasesA
Read-onlyIdempotent

List DHCP leases handed out by the firewall, across the Kea and legacy ISC backends.

Leases map MAC addresses to IPs and hostnames, which is usually the best way to put a name to a device seen in firewall logs. A device with a static IP will not appear here; check opnsense_search_neighbors instead.

Args: params (DhcpLeasesInput): Validated input containing: - search (str): Filter on IP, MAC or hostname (default: "") - backend (str): "auto", "kea" or "isc" (default: "auto") - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "backend": "kea"|"isc", "leases": [ {"address": str, "hwaddr": str, "hostname": str, "if_descr": str, "state": str, "expire": str} ] }

Examples: - Use when: "Who has 192.168.30.57?" -> search="192.168.30.57" - Use when: "List everything on the IOT VLAN" -> search="192.168.30." - Don't use when: The host is statically addressed (use opnsense_search_neighbors)

Inputs: params (required). Returns: result

opnsense_list_interfacesA
Read-onlyIdempotent

List the firewall's interfaces with their config name, device name, addresses and link status.

This is the mapping tool for the rest of the server. Firewall rules reference the config name (lan, wan, opt1...), while diagnostics, ARP entries and counters report the device name (igb0, vlan0.30, pppoe0). Call this first whenever a question spans both worlds, for example "which rules apply to the IOT VLAN".

Args: params (ListInterfacesInput): Validated input containing: - search (str): Substring filter (default: "") - include_disabled (bool): Include down interfaces (default: True) - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "interfaces": [ { "identifier": str, # config name, e.g. "opt2" "device": str, # device name, e.g. "vlan0.30" "description": str, # label shown in the GUI, e.g. "IOT" "status": str, # "up" / "down" / "no carrier" "ipv4_address": str, "ipv6_address": str, "macaddr": str, "enabled": bool } ] }

Examples: - Use when: "What VLANs are configured?" -> search="vlan" - Use when: "Which device is the GUEST network?" -> search="GUEST" - Don't use when: You want throughput counters (use opnsense_get_interface_statistics)

Inputs: params (required). Returns: result

opnsense_list_servicesA
Read-onlyIdempotent

List services registered with OPNsense and whether each one is running.

Covers core services (unbound, openvpn, ntpd) and plugin services (crowdsec, wireguard, os-* plugins). Use this to get the exact service id before calling opnsense_control_service.

Args: params (ListServicesInput): Validated input containing: - search (str): Substring filter on name/description (default: "") - running_only (bool): Only running services (default: False) - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "services": [ {"name": str, "description": str, "running": int, "locked": int} ] }

Examples: - Use when: "Is unbound running?" -> search="unbound" - Use when: "What services are stopped?" -> running_only=False, then read the column - Don't use when: You want to restart something (use opnsense_control_service)

Inputs: params (required). Returns: result

opnsense_query_firewall_statesA
Read-only

Query the pf state table to see connections currently tracked by the firewall.

States show what is happening now, while the log shows what happened. A host with many states to one destination is actively communicating; a host with none is not, regardless of what the rules permit. Byte and packet counts per state make this a good way to find which client is consuming a link.

Args: params (QueryStatesInput): Validated input containing: - filter (str): Address or port to match (default: "" = all states) - rule_id (str): Restrict to a specific rule id (default: "") - limit (int): Max states to return, 1-200 (default: 25) - offset (int): States to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "states": [ {"iface": str, "proto": str, "src_addr": str, "src_port": str, "dst_addr": str, "dst_port": str, "state": str, "packets": int, "bytes": int, "age": int, "expires": int, "id": str, "creatorid": str} ] }

Examples: - Use when: "Is this host talking to anything right now?" -> filter="192.168.30.57" - Use when: "What's saturating the WAN?" -> filter="", sort by bytes in the output - Don't use when: You need history (use opnsense_get_firewall_log)

Inputs: params (required). Returns: result

opnsense_search_aliasesA
Read-onlyIdempotent

Search configured firewall aliases and their types, contents and descriptions.

This returns the alias configuration. For a URL table or GeoIP alias the configured value is a feed URL or a country list, not the addresses currently loaded; use opnsense_get_alias_contents to see what pf actually holds.

Args: params (SearchAliasesInput): Validated input containing: - search (str): Free-text filter (default: "") - alias_type (str): Restrict to one alias type (default: "") - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "aliases": [ {"uuid": str, "name": str, "type": str, "enabled": str, "content": str, "description": str} ] }

Examples: - Use when: "What aliases exist?" -> search="" - Use when: "Show me the GeoIP aliases" -> alias_type="geoip" - Don't use when: You want the addresses currently in the table (use opnsense_get_alias_contents)

Inputs: params (required). Returns: result

opnsense_search_dns_queriesA
Read-only

Search recent DNS lookups seen by the Unbound resolver, including which client asked and whether the answer was blocked.

This requires Unbound's reporting to be enabled in Services -> Unbound DNS -> Reporting; without it the resolver answers queries but records nothing and this tool returns an empty result even on a busy network.

Pair this with the firewall log when a client behaves oddly: a device resolving domains it should not, or a blocklist hit the user did not expect, both show up here and in neither the rule set nor the state table.

Args: params (DnsQueriesInput): Validated input containing: - search (str): Filter on domain, client or blocklist (default: "") - blocked_only (bool): Only blocked queries (default: False) - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "queries": [ {"time": str, "client": str, "type": str, "domain": str, "action": str, "blocklist": str, "rcode": str} ] }

Examples: - Use when: "What did this device look up?" -> search="192.168.30.57" - Use when: "Is anything hitting the blocklist?" -> blocked_only=True

Inputs: params (required). Returns: result

opnsense_search_firewall_rulesA
Read-onlyIdempotent

Search firewall filter rules and return them in evaluation order with their action, interface, source, destination and description.

Rules are evaluated top to bottom and the last match wins unless a rule sets quick. The 'sequence' column reflects ordering, so when diagnosing "why is this traffic blocked", read the matching rules in sequence order rather than assuming the first match applies.

Scope note: this reads the MVC filter model, which is what Firewall -> Rules uses on current OPNsense releases. On older releases some legacy rules may live outside this model and will not appear.

Args: params (SearchRulesInput): Validated input containing: - search (str): Free-text filter (default: "") - enabled_only (bool): Skip disabled rules (default: False) - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "rules": [ { "uuid": str, # pass to opnsense_get_firewall_rule "sequence": str, "enabled": str, "action": str, # "pass", "block", "reject" "interface": str, "direction": str, "ipprotocol": str, "protocol": str, "source_net": str, "source_port": str, "destination_net": str, "destination_port": str, "description": str } ] }

Examples: - Use when: "Which rules mention the IOT VLAN?" -> search="IOT" - Use when: "What blocks port 445?" -> search="445" - Don't use when: You want NAT rules (those live under firewall/source_nat and firewall/d_nat, reachable via opnsense_api_request)

Inputs: params (required). Returns: result

opnsense_search_neighborsA
Read-onlyIdempotent

Search the ARP (IPv4) and NDP (IPv6) neighbour tables to find which device holds an address, or which addresses a MAC has.

This is the fastest way to identify an unknown host on a segment. Entries only exist for devices that have communicated recently, so an absent entry does not prove a device is offline. For a fuller picture of a specific segment, pair this with opnsense_list_dhcp_leases.

Args: params (SearchNeighboursInput): Validated input containing: - search (str): Substring on IP, MAC, hostname or interface (default: "") - family (str): "ipv4", "ipv6" or "both" (default: "ipv4") - resolve_hostnames (bool): Resolve names, slower (default: False) - limit (int): Max records, 1-200 (default: 25) - offset (int): Records to skip (default: 0) - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Markdown table, or JSON with this schema: { "total": int, "count": int, "offset": int, "has_more": bool, "next_offset": int|null, "neighbors": [ {"ip": str, "mac": str, "intf": str, "hostname": str, "manufacturer": str, "expires": int, "family": "ipv4"|"ipv6"} ] }

Examples: - Use when: "What is 192.168.30.57?" -> search="192.168.30.57" - Use when: "Which IPs does this MAC hold?" -> search="a4:83:e7:11:22:33", family="both" - Don't use when: You want the full DHCP allocation (use opnsense_list_dhcp_leases)

Inputs: params (required). Returns: result

opnsense_toggle_firewall_ruleA
DestructiveIdempotent

Enable or disable a single firewall rule.

Requires OPNSENSE_ALLOW_WRITE=true. The change is staged, not live: nothing takes effect until opnsense_apply_firewall_changes runs. Take a savepoint before toggling anything that could affect your own access path, so an unreachable firewall reverts itself after 60 seconds instead of needing console access.

Args: params (ToggleRuleInput): Validated input containing: - uuid (str): Rule UUID - enabled (bool): True to enable, False to disable - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Confirmation text noting that an apply is still required, or JSON: {"result": str, "uuid": str, "enabled": bool, "applied": false}

Error Handling: - Returns a write-disabled explanation when OPNSENSE_ALLOW_WRITE is not set - Returns a not-found message when the UUID does not exist

Inputs: params (required). Returns: result

opnsense_update_alias_entriesA
Destructive

Add or remove entries in an alias table.

Requires OPNSENSE_ALLOW_WRITE=true. Unlike rule edits, these changes take effect immediately: the entry is written into the running pf table without an apply step and without a savepoint to roll back to. That makes this the right tool for blocking an address quickly, and the wrong tool for anything you have not verified, because adding a network to an alias that a block rule references can cut off traffic you depend on.

Entries are applied one at a time; the result reports each outcome separately so a partial failure is visible rather than silent.

Args: params (UpdateAliasEntriesInput): Validated input containing: - name (str): Alias name - action (str): "add" or "delete" - entries (list[str]): 1-100 IPs, networks or hostnames - response_format (ResponseFormat): 'markdown' or 'json'

Returns: str: Per-entry outcome, or JSON with this schema: { "alias": str, "action": str, "results": [{"entry": str, "status": str, "detail": str}], "succeeded": int, "failed": int }

Error Handling: - Returns a write-disabled explanation when OPNSENSE_ALLOW_WRITE is not set - Reports per-entry failures without aborting the remaining entries

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 26 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: aliases are split into config, live table, references, and updates; firewall diagnostics are split into log, states, statistics, and kill; rules are split into search, detail, statistics, toggle, and apply. Cross-references explicitly warn against using the wrong tool, so an agent should rarely select the wrong one.

    Naming Consistency4/5

    All tools use the opnsense_verb_noun pattern with snake_case, which is consistent. However, verbs vary for similar operations: search_aliases vs list_interfaces vs get_routes, and query_states vs search_dns_queries. The differences are mostly intentional (search for filtered, list for enumeration, get for single item), but the boundary is not perfectly uniform.

    Tool Count4/5

    26 tools is slightly above the typical well-scoped range, but the breadth of the OPNsense domain justifies the number. Each tool covers a distinct feature area (aliases, rules, states, DNS, VPN, interfaces, DHCP, system, services), so none feels redundant. The count is high but not excessive given the scope.

    Completeness4/5

    The tool surface covers most core firewall workflows: searching and modifying rules, inspecting aliases and live tables, querying states and logs, checking DNS and VPN status, and managing services. Gaps exist for creating/deleting rules and aliases, but these are intentionally left out for safety, and opnsense_api_request provides a raw fallback for any missing endpoint.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables interaction with Firewalla network security devices for network monitoring, device management, traffic analysis, and security rule configuration through MCP tools.
      -
    • A
      license
      A
      quality
      B
      maintenance
      A secure MCP server for managing OPNsense firewalls through AI assistants. Provides 81 tools across system, firewall, network, DNS, DHCP, VPN, HAProxy, services, diagnostics, and security domains.
      81
      317 PyPI
      27
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides complete programmatic access to OPNsense core APIs, enabling firewall automation, VPN management, and system administration through a comprehensive MCP server.
      MIT