opnsense-mcp
Provides tools to manage firewall rules, view network interfaces, manage DHCP leases, and monitor system status on an OPNsense firewall.
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-mcp Show me the active DHCP leases"
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-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 --versionCreate an API key
In the OPNsense GUI: System → Access → Users
Edit the user the server should act as (create a dedicated one — see Least privilege)
Under API keys, press +. A
apikey.txtdownloads containingkeyandsecret. 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.pemDisable 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=falseConfiguration
All configuration is environment-only. Credentials never appear in tool arguments, so they cannot end up in a conversation transcript.
Variable | Default | Purpose |
|
| Base URL including scheme |
| (unset) | API key |
| (unset) | API secret |
| (unset) | Path to a PEM file; takes precedence over |
|
| Set |
|
| Request timeout in seconds |
|
| 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.mdis 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'suvlookup.Claude Desktop: install
opnsense-mcp-0.1.1.mcpbvia Settings -> Extensions. Credentials go to your OS keychain, not a config file. Build it withcp -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.shrather 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 /mcpRuns 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 |
| Version, uptime, load, memory, temperature, disk. Sections whose endpoint is missing are omitted rather than failing the call |
| Pending updates and installed vs latest version |
| Core and plugin services with running state |
| write — start / stop / restart |
Network
Tool | Notes |
| Maps config names ( |
| Cumulative counters, not rates — call twice and difference |
| ARP and NDP tables, |
| Active routing table |
| Kea with automatic fallback to legacy ISC |
Firewall rules
Tool | Notes |
| Rules in evaluation order with action, interface, source, destination |
| Full record by UUID; enum fields flattened from OPNsense's |
| Per-rule evaluations / packets / bytes / states. |
| write — stages only; nothing is live until applied |
| write — savepoint / apply / cancel_rollback / revert |
Aliases
Tool | Notes |
| Alias configuration |
| What the pf table actually holds — the two diverge when a URL table or GeoIP feed fails to refresh |
| What breaks if this alias changes |
| write — add/remove entries; live immediately, per-entry outcomes reported |
Live diagnostics
Tool | Notes |
| Recent entries filtered by verdict / interface / address / port / protocol |
| pf state table — what is happening now |
| State table usage, memory limits, drop counters |
| write — drop states matching an address; wildcards rejected |
DNS and VPN
Tool | Notes |
| Unbound service state, blocklist status, cache counters |
| Recent lookups per client; needs Reporting enabled under Services → Unbound DNS |
| WireGuard peers and OpenVPN sessions |
Escape hatch
Tool | Notes |
| Any endpoint. GET always allowed; POST needs |
Command names in the published API reference are snake_case; URLs use camelCase.
get_interface_names → getInterfaceNames.
Resources
opnsense://interfaces— the interface map as JSONopnsense://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 permanentSkipping 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 |
| Self-signed WebGUI cert. Set |
| Wrong key/secret, or the key's user has no API access |
| Missing ACL for that page. Check Effective Privileges |
| Plugin not installed, or this OPNsense release predates it |
Returned HTML instead of JSON |
|
Read timeout | Large state tables and log queries are slow. Lower |
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 -qTwenty-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 abstractleasescontroller, so the concrete v4 controller name is an inferencedhcpv4/leases/searchLease(ISC fallback) andopenvpn/service/searchSessionsRequest body key shapes:
alias_util add/delete(address),killStates(filter),findReferences(alias)diagnostics/firewall/logserver-side filter parameters — rather than guess, the tool fetches a window and filters locally, which is why it reportswindow_sizeand 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 toolsopnsense_api_requestADestructive
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_changesADestructive
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:
mode='savepoint' -> returns a revision timestamp
make changes -> e.g. opnsense_toggle_firewall_rule
mode='apply' -> with revision=<from step 1>; the firewall will revert to that revision by itself in 60 seconds
verify connectivity -> confirm the firewall is still reachable
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_serviceADestructive
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_referencesARead-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_contentsARead-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_overviewARead-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_logARead-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_ruleARead-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_statusARead-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_statisticsARead-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_statisticsARead-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_routesARead-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_statisticsARead-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_statusARead-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_statusARead-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_statesADestructive
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_leasesARead-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_interfacesARead-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_servicesARead-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_statesARead-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_aliasesARead-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_queriesARead-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_rulesARead-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_neighborsARead-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_ruleADestructiveIdempotent
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_entriesADestructive
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
Scored across 26 tools
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.
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.
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.
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
Related MCP Connectors
Tailscale device, route, DNS, key, user, and ACL management over MCP and CLI.
Manage CloudPepper servers, Odoo instances, backups, and deployments over MCP.
Crypto transaction firewall and risk tools for MCP agents.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables interaction with Firewalla network security devices for network monitoring, device management, traffic analysis, and security rule configuration through MCP tools.-
- AlicenseAqualityBmaintenanceA 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.81317 PyPI27MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to manage OPNsense firewall, interfaces, DHCP, DNS, routes, and services via natural language through 42 MCP tools.1MIT
- AlicenseNot gradedqualityDmaintenanceProvides complete programmatic access to OPNsense core APIs, enabling firewall automation, VPN management, and system administration through a comprehensive MCP server.MIT