OPNsense MCP Server
A secure, read-only-by-default MCP server that gives AI assistants 80+ tools to inspect and (with explicit opt-in) modify an OPNsense firewall through its MVC API.
System & config — firmware/product status, service list, gateway health, full
config.xmlbackup (sensitive data redacted by default), plus a cached config scan and per-section JSON queries (including legacy GUI rules).Firewall — list MVC filter rules, aliases, NAT rules, categories, and logs; create/update/delete/toggle rules, aliases, NAT forwards, and categories; bulk-create required ICMPv6 rules. Firewall writes use 60-second savepoint auto-revert on OPNsense < 26.7 and apply immediately on 26.7+ (
opn_confirm_changesto commit).Network — interface traffic stats, ARP and NDP tables, IPv6 address status per interface, static routes.
DNS — Unbound host overrides, forward zones, resolver stats, DNSBL blocklist configs (view/set/allowlist management/reload), and Unbound reconfigure.
DHCP — lease views for ISC, Kea, and dnsmasq; dnsmasq range CRUD including IPv6 ranges with Router Advertisement modes.
VPN — WireGuard, IPsec (Phase 1/2), and OpenVPN status.
HAProxy — status, searchable CRUD for all resource types (frontends, backends, servers, ACLs, actions, health checks, etc.), config syntax validation, and reconfigure.
Services — ACME certificates, cron jobs, CrowdSec status/alerts, Dynamic DNS account CRUD, mDNS Repeater status and configuration.
Diagnostics — ping, traceroute, DNS lookup from the firewall, and PF state table queries.
Security — an 11-area security audit with severity-ranked findings and PCI DSS / BSI / NIST / CIS compliance references.
Safety controls — writes blocked unless
OPNSENSE_ALLOW_WRITES=true, dangerous endpoints (halt/reboot/poweroff/firmware upgrade) hard-blocked, sensitive data gated behindOPNSENSE_ALLOW_SENSITIVE, STDIO-only transport, and no SSH or shell access.
Provides tools for managing OPNsense firewalls, including system status, firewall rules, network diagnostics, DNS, DHCP, VPN, HAProxy, services, and security settings.
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 Server show me the current firewall rules"
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 Server
A secure Model Context Protocol (MCP) server for managing OPNsense firewalls through AI assistants like Claude Code, Cursor, and other MCP-compatible tools.
81 tools across 10 domains: system, firewall, network, DNS, DHCP, VPN, HAProxy, services, diagnostics, and security.
Requirements
Python 3.11+
OPNsense 24.7 or newer — the MCP server relies on the MVC-based API endpoints introduced in OPNsense 24.7. Older versions use a different API structure that is not compatible. The server auto-detects the OPNsense version on first connect and selects the correct endpoint naming (camelCase for pre-25.7, snake_case for 25.7+). OPNsense 26.x is fully supported, including its changed firmware status response format.
Related MCP server: OPNsense MCP Server
Security Model
This MCP server is designed with security as the primary concern:
Read-only by default — write operations require explicit opt-in via
OPNSENSE_ALLOW_WRITES=trueSavepoint/rollback (OPNsense < 26.7 only) — where OPNsense still offers the savepoint API, firewall modifications use its built-in 60-second auto-revert; changes must be explicitly confirmed or they roll back automatically. OPNsense 26.7 removed that API upstream — the server detects the missing endpoint at runtime and applies firewall changes immediately, with no automatic rollback
Endpoint blocklist — dangerous endpoints (
halt,reboot,poweroff,firmware update/upgrade) are hard-blocked at the API client level and can never be calledAPI-only — no SSH access, no command execution, no direct config file manipulation
Local transport — STDIO only, no network-exposed HTTP/SSE endpoints
No credential exposure — API keys are never included in tool output, logs, or error messages
Input validation — hostname parameters are validated against shell metacharacter injection
Sensitive data stripping — config backup strips passwords and keys by default
Quick Start
1. Create an OPNsense API Key
Log in to your OPNsense web interface
Go to System > Access > Users
Either edit an existing user or create a dedicated API user:
For production use, create a dedicated user (e.g.,
mcp-api) with only the privileges neededFor read-only access, assign the user to a group with read-only API access
Scroll down to the API keys section and click the + button
A key/secret pair will be generated and a file (
apikey.txt) will be downloadedThe file contains two lines —
key=your-api-key-hereandsecret=your-api-secret-hereStore these credentials securely — the secret cannot be retrieved again from OPNsense
Tip: For a read-only setup (recommended for getting started), you don't need to change any permissions — the default API access is sufficient for all read-only tools.
2. Install
# Using pip
pip install opnsense-mcp-server
# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server
# Using Docker
docker pull uhlenheide/opnsense-mcp-server
# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .Docker image: the official image is
uhlenheide/opnsense-mcp-server, published from this repository by.github/workflows/publish-docker.ymlon everyv*tag. There is nolucamarien/opnsense-mcp-serverimage — earlier README versions named it by mistake.
3. Configure Your AI Assistant
Claude Code
Add to your project's .mcp.json:
{
"mcpServers": {
"opnsense": {
"command": "opnsense-mcp",
"env": {
"OPNSENSE_URL": "https://192.168.1.1/api",
"OPNSENSE_API_KEY": "your-api-key-here",
"OPNSENSE_API_SECRET": "your-api-secret-here",
"OPNSENSE_VERIFY_SSL": "false",
"OPNSENSE_ALLOW_WRITES": "false"
}
}
}
}Alternative: Use
"command": "python", "args": ["-m", "opnsense_mcp"]if theopnsense-mcpCLI is not on your PATH.
Or add it globally to ~/.claude/claude_code_config.json.
Claude Code (Docker)
{
"mcpServers": {
"opnsense": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "OPNSENSE_URL=https://192.168.1.1/api",
"-e", "OPNSENSE_API_KEY=your-api-key-here",
"-e", "OPNSENSE_API_SECRET=your-api-secret-here",
"-e", "OPNSENSE_VERIFY_SSL=false",
"-e", "OPNSENSE_ALLOW_WRITES=false",
"uhlenheide/opnsense-mcp-server"
]
}
}
}Cursor
Add to your Cursor MCP settings (Settings > MCP):
{
"mcpServers": {
"opnsense": {
"command": "opnsense-mcp",
"env": {
"OPNSENSE_URL": "https://192.168.1.1/api",
"OPNSENSE_API_KEY": "your-api-key-here",
"OPNSENSE_API_SECRET": "your-api-secret-here",
"OPNSENSE_VERIFY_SSL": "false"
}
}
}
}Configuration
Environment Variable | Default | Description |
| (required) | OPNsense API base URL (must end with |
| (required) | API key from OPNsense user settings |
| (required) | API secret from OPNsense user settings |
|
| Verify SSL certificate ( |
|
| Enable write operations (firewall rules, service control) |
|
| Permit |
Custom ports: If your OPNsense web GUI runs on a non-standard port (e.g., 10443), include it in the URL: https://192.168.1.1:10443/api
Available Tools (81)
System (7 tools)
Tool | Description |
| System info including firmware version, product name, and architecture |
| List all services and their running status. Params: |
| Gateway availability, latency, and dpinger health checks |
| Download |
| Scan the full configuration, parse it into sections, and collect runtime inventory (firmware, plugins, DHCP, DNS, interfaces, services). Results are cached per session. Params: |
| Get a specific config section as structured JSON. Params: |
| MCP server version, write mode status, detected OPNsense version, API style, and whether firewall writes still get savepoint/rollback protection |
Network (5 tools)
Tool | Description |
| Per-interface traffic statistics (bytes in/out, packets, errors) |
| ARP table showing IP-to-MAC address mappings |
| NDP (Neighbor Discovery Protocol) table showing IPv6-to-MAC address mappings |
| IPv6 configuration and address status for all interfaces (method, live addresses, summary) |
| Configured static routes. Params: |
Firewall (21 tools)
Tool | Description | Writes |
| List MVC firewall filter rules. Params: | No |
| List alias definitions (IP lists, port groups, GeoIP, URLs). Params: | No |
| List NAT port forwarding (DNAT) rules. Params: | No |
| List firewall rule categories and their UUIDs. Params: | No |
| Recent firewall log entries with client-side filtering. Params: | No |
| Confirm pending changes, cancelling 60-second auto-rollback (OPNsense < 26.7; a no-op returning | Yes |
| Toggle a rule's enabled/disabled state with savepoint (OPNsense < 26.7). Params: | Yes |
| Create a new filter rule with savepoint (OPNsense < 26.7). Params: | Yes |
| Delete a filter rule by UUID with savepoint (OPNsense < 26.7). Params: | Yes |
| Create a new alias. Params: | Yes |
| Create a NAT port forwarding rule with savepoint (OPNsense < 26.7). Params: | Yes |
| Create a new firewall rule category. Params: | Yes |
| Delete a firewall rule category by UUID with savepoint (OPNsense < 26.7). Params: | Yes |
| Assign categories to a firewall rule with savepoint (OPNsense < 26.7). Params: | Yes |
| Create essential ICMPv6 rules required for IPv6 operation (NDP, RA, ping6) per RFC 4890. Params: | Yes |
| Update an existing alias (name, content, type, description). Read-modify-write. Params: | Yes |
| Delete an alias by UUID. Check rule references first. Params: | Yes |
| Toggle alias enabled/disabled state. Params: | Yes |
| Update filter rule fields with savepoint (OPNsense < 26.7). Params: | Yes |
| Update NAT port forwarding rule with savepoint (OPNsense < 26.7). Params: | Yes |
| Delete a NAT port forwarding rule by UUID with savepoint (OPNsense < 26.7). Params: | Yes |
Note: Savepoint protection only exists on OPNsense < 26.7. On 26.7+ these tools apply changes immediately and permanently — see Write Operations and Savepoints.
DNS (13 tools)
Tool | Description | Writes |
| Unbound host overrides (local DNS records). Params: | No |
| DNS forward zones (domain-specific servers). Params: | No |
| Unbound resolver statistics (queries, cache hits, uptime) | No |
| Apply pending DNS resolver configuration changes | Yes |
| Add an Unbound DNS host override (A/AAAA record) and apply immediately. Params: | Yes |
| List DNSBL blocklist configurations with providers and status. Params: | No |
| Get full DNSBL configuration by UUID (providers, allowlists, settings). Params: | No |
| Update DNSBL settings (read-modify-write). Params: | Yes |
| Add domains to DNSBL allowlist without overwriting. Params: | Yes |
| Remove domains from DNSBL allowlist. Params: | Yes |
| Reload DNSBL blocklist files and restart Unbound (no config change, recovery tool) | Yes |
| Update an Unbound DNS host override and apply immediately. Params: | Yes |
| Delete an Unbound DNS host override and apply immediately. Params: | Yes |
DHCP (8 tools)
Tool | Description | Writes |
| Active DHCPv4 leases from the ISC DHCP server | No |
| DHCPv4 leases from the Kea DHCP server. Params: | No |
| DHCPv4 and DHCPv6 leases from the dnsmasq DNS/DHCP server. Params: | No |
| Configured DHCP address ranges (both DHCPv4 and DHCPv6 with RA config). Params: | No |
| Create a new DHCP range (IPv4 or IPv6 with Router Advertisement configuration). Params: | Yes |
| Apply pending dnsmasq DNS/DHCP configuration changes | Yes |
| Update a DHCP range (addresses, lease time, RA config) and apply. Params: | Yes |
| Delete a DHCP range by UUID and apply. Params: | Yes |
VPN (3 tools)
Tool | Description |
| WireGuard tunnel and peer status (requires os-wireguard plugin) |
| IPsec VPN tunnel status — IKE (Phase 1) and ESP/AH (Phase 2) sessions |
| OpenVPN connection status — instances, sessions, and routes |
HAProxy (8 tools)
Full configuration management for the HAProxy load balancer (requires os-haproxy plugin).
Tool | Description | Writes |
| HAProxy service status and backend health | No |
| Search HAProxy resources by type. Params: | No |
| Get detailed configuration for a specific resource. Params: | No |
| Validate HAProxy configuration syntax before applying | No |
| Create a new HAProxy resource. Params: | Yes |
| Update an existing HAProxy resource (partial updates). Params: | Yes |
| Delete a HAProxy resource by UUID. Params: | Yes |
| Apply pending HAProxy configuration changes | Yes |
Note: HAProxy changes do NOT use savepoint protection — they apply immediately on reconfigure. Always call
opn_haproxy_configtestbeforeopn_reconfigure_haproxy.
Services (11 tools)
Tool | Description | Writes |
| ACME/Let's Encrypt certificates and their status. Params: | No |
| Scheduled cron jobs. Params: | No |
| CrowdSec security engine status and active decisions | No |
| CrowdSec security alerts (detected threats). Params: | No |
| Dynamic DNS accounts and their update status. Params: | No |
| Create a new Dynamic DNS account. Params: | Yes |
| Apply pending Dynamic DNS configuration changes | Yes |
| Update a Dynamic DNS account (password is write-only). Params: | Yes |
| Delete a Dynamic DNS account by UUID. Params: | Yes |
| mDNS Repeater status and configuration (enabled, interfaces, blocklist). Requires | No |
| Configure mDNS Repeater for cross-VLAN device discovery (HomeKit, Chromecast, AirPlay). Params: | Yes |
Diagnostics (4 tools)
Tool | Description |
| Ping a host from the firewall to test connectivity. Params: |
| Trace network path to a destination. Params: |
| DNS lookup from the firewall. Params: |
| Query active PF state table. Params: |
Security (1 tool)
Tool | Description |
| Comprehensive 11-area security audit: firmware, firewall rules (MVC + legacy, port grouping, insecure protocols), NAT forwarding, DNS security (DNSSEC, DoT), system hardening (SSH, HTTPS, syslog), services, certificates (ACME + system + CAs), VPN (WireGuard config, IPsec, OpenVPN), HAProxy (headers, health checks), gateways. Findings tagged with PCI DSS v4.0, BSI IT-Grundschutz, NIST 800-41, CIS compliance references. |
Write Operations and Savepoints
Write operations require OPNSENSE_ALLOW_WRITES=true. On OPNsense < 26.7, firewall changes additionally go through OPNsense's savepoint mechanism:
Before any firewall change, a savepoint is created automatically
The change is applied (rule toggle, add, or delete)
A 60-second countdown starts — if not confirmed, OPNsense automatically reverts the change
Use
opn_confirm_changeswith the returnedrevisionto make changes permanent
On those versions, if an AI assistant makes a bad firewall change that locks you out, the change reverts automatically within 60 seconds.
OPNsense 26.7 removed the savepoint/rollback API upstream, so there is no auto-revert on 26.7+. The server does not hardcode a version cut-off: it probes for the savepoint endpoint on the first firewall write and, if OPNsense answers that the endpoint does not exist, degrades to direct apply for the rest of the session. Check opn_mcp_info — its savepoint_support field reports true, false, or null if no write has probed yet. Write tools then return an empty revision, opn_confirm_changes answers with status: "not_applicable", and every firewall change is immediate and permanent.
Warning: On OPNsense 26.7+ take a config backup (
opn_download_config, or System > Configuration > Backups) before enabling writes, and keep out-of-band access to the box — a rule that locks you out will not revert itself.
Note:
opn_reconfigure_unbound,opn_reconfigure_haproxy,opn_reconfigure_ddclient,opn_reconfigure_dnsmasq, andopn_configure_mdns_repeaterrequire writes but don't use savepoints — they apply service configuration changes and are not automatically revertible.
IPv6 Support
Fully Automated via MCP
IPv6 Firewall Rules — Create rules with
ip_protocol="inet6"(savepoint-protected on OPNsense < 26.7)HAProxy IPv6 Bindings — Frontends with
[::]:443or[2001:db8::1]:443bind addressesHAProxy IPv6 Backends — Servers with IPv6 addresses,
resolvePrefer: ipv6on backendsDynamic DNS with IPv6 — DDNS accounts with IPv6-capable checkip methods
DHCPv6 Ranges (dnsmasq) — IPv6 DHCP ranges with Router Advertisement configuration
DNS AAAA Records — Unbound host overrides with IPv6 addresses
IPv6 Diagnostics — Traceroute with
ip_version="6", ping via hostname
Requires Manual GUI Configuration
These settings lack MVC API support in OPNsense and must be configured via the web GUI:
WAN IPv6 setup — PPPoE with DHCPv6 prefix delegation, static IPv6, SLAAC
LAN IPv6 addressing — Track Interface mode, static /64 assignment, prefix ID
Interface assignment — Assigning physical ports to WAN/LAN/OPT roles
6to4/6rd tunnels — Transition tunnel mechanisms
Known Limitations
ISC DHCP / Kea DHCPv6: Not implemented. Only dnsmasq (the modern default) is supported for DHCPv6 ranges and Router Advertisements. ISC DHCP is deprecated; Kea DHCPv6 lease visibility is limited in the API.
radvd: Not implemented as a separate tool set. Dnsmasq handles Router Advertisements natively via range configuration. Only one RA daemon should run per interface.
Dual-stack firewall rules:
inet46(dual-stack) works correctly in MVC API rules (opn_add_firewall_rule). However,inet46in legacy XML filter rules (GUI) silently produces no PF output — this is a known OPNsense bug that only affects legacy rules.Legacy GUI rules: Firewall rules created via the traditional OPNsense GUI are not accessible through the MVC API. Use
opn_get_config_section("filter")for read-only access.
Recommended IPv6 Migration Workflow
Manual (GUI): Configure WAN IPv6 (DHCPv6-PD from ISP or static)
Manual (GUI): Configure LAN interfaces (Track Interface mode for prefix delegation)
MCP: Configure Router Advertisements via
opn_add_dnsmasq_rangewith RA flagsMCP: Create IPv6 firewall rules (ICMPv6 must be allowed for NDP/RA/PMTUD)
MCP: Add IPv6 DNS records via
opn_add_dns_overrideMCP: Configure Dynamic DNS with IPv6 checkip method
MCP: Add IPv6 bind addresses to HAProxy frontends
MCP: Verify with
opn_ping,opn_traceroute(ip_version="6"),opn_gateway_status
Version Compatibility
OPNsense Version | Status |
24.7 (Thriving Tiger) | Supported |
25.1 (Ultimate Unicorn) | Supported |
25.7 (Visionary Viper) | Supported (auto-detects snake_case API) |
26.1+ | Supported |
The server automatically detects the OPNsense version on first connection and selects the correct API endpoint naming convention (camelCase for pre-25.7, snake_case for 25.7+).
Note on firewall rules: opn_list_firewall_rules shows rules managed via the MVC/automation API. Rules configured through the OPNsense GUI use a legacy format not accessible via this API. This is a known OPNsense limitation.
Troubleshooting
Connection Issues
"Connection refused" or timeout errors
Verify
OPNSENSE_URLends with/api(e.g.,https://192.168.1.1/api)If using a non-standard port, include it:
https://192.168.1.1:10443/apiEnsure the OPNsense web GUI is accessible from the machine running the MCP server
SSL certificate errors
For self-signed certificates (default OPNsense setup), set
OPNSENSE_VERIFY_SSL=falseFor production, install a proper certificate on OPNsense and keep
OPNSENSE_VERIFY_SSL=true
Authentication Issues
401 Unauthorized
Verify
OPNSENSE_API_KEYandOPNSENSE_API_SECRETare correctAPI keys are case-sensitive — copy them exactly from the downloaded
apikey.txtCheck that the API user is not disabled in OPNsense
Verify the API user has sufficient privileges for the operations you're attempting
403 Forbidden
The API user may lack permissions for the requested endpoint
For write operations, ensure
OPNSENSE_ALLOW_WRITES=trueis set
Tool-Specific Issues
opn_list_firewall_rules returns empty results
This tool only shows MVC/automation rules, not legacy GUI rules
Create rules via the automation API or
opn_add_firewall_ruleto see them
opn_ping times out
The firewall may not have a route to the target host
Check gateway status with
opn_gateway_statusDefault timeout is 30 seconds (30 poll cycles)
opn_download_config shows [REDACTED] values
This is the default behavior for security. To include passwords and keys, set
OPNSENSE_ALLOW_SENSITIVE=truein the server environment and passinclude_sensitive=true(use with caution in AI conversations)
Write operations fail with "writes not enabled"
Set
OPNSENSE_ALLOW_WRITES=truein your MCP server configurationThis is intentionally disabled by default for safety
Savepoint confirmation fails
The
revisionparameter must match exactly what was returned by the write operationConfirmations must happen within 60 seconds or the change auto-reverts
On OPNsense 26.7+ there is no savepoint API: write tools return an empty
revisionandopn_confirm_changesreturnsstatus: "not_applicable". That is expected, not a failure — the change already applied permanently
Diagnostic Commands
If you need to debug the MCP server:
# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status
# Run the server directly
python -m opnsense_mcp
# Run tests to verify installation
pytest -vDevelopment
# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"
# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v
# Full CI pipeline (lint, format, type check, security scan, tests)
make validate
# Individual checks
ruff check src/ tests/ # Lint (includes bandit security checks)
ruff format src/ tests/ # Format
mypy src/ --strict # Type checkingBest Practices
Domain-specific guides for common firewall configuration tasks:
WhatsApp Calling Firewall Rules — Allow WhatsApp voice/video calls through a default-deny firewall using URL table aliases and scoped rules
These guides show real-world MCP tool usage patterns and explain the security considerations behind each approach.
Contributing
See CONTRIBUTING.md for detailed guidelines. Key points:
All tests must use mocked API responses — never connect to a real OPNsense
No overlapping tools — each tool must have a distinct purpose
Write clear docstrings — they're the AI's only guide to tool selection
Return structured data (dicts), not formatted strings
Run
make validatebefore submitting
License
MIT
Available Tools
81 toolsopn_add_aliasA
Create a new firewall alias (IP list, network group, port group, etc.).
Use this when you need to create a reusable alias for use in firewall rules. Aliases group IPs, networks, or ports under a single name.
This does NOT require savepoint protection — aliases are metadata definitions that only affect traffic when referenced by a firewall rule.
Parameters:
name: alias name (alphanumeric and underscores only, no spaces)
alias_type: 'host' (IPs), 'network' (CIDRs), 'port' (ports/ranges), 'urltable' (URL-based IP list), 'geoip' (country codes)
content: alias entries separated by newlines. For GeoIP, use country codes (one per line, e.g. 'DE\nFR\nNL'). For host/network, use IPs/CIDRs.
description: human-readable description
Returns: dict with 'result' (str) and 'uuid' (str) of the new alias.
Inputs: name (required), content, alias_type, description. Returns: object
opn_add_ddns_accountA
Create a new Dynamic DNS account and apply the configuration.
Use this to register a hostname with a DDNS provider so the firewall automatically updates the DNS record when the public IP changes.
Inputs: service (required), hostname (required), checkip, password, +3 more. Returns: object
opn_add_dnsbl_allowlistA
Add domains to a DNSBL allowlist (whitelist) without overwriting existing entries.
Use this when a domain is blocked by DNSBL and you need to allowlist it (e.g. googleads.g.doubleclick.net blocking YouTube). Existing allowlist entries are preserved. Changes are applied immediately.
Get the UUID from opn_list_dnsbl first.
Parameters:
uuid: blocklist UUID from opn_list_dnsbl
domains: domains to add, comma or newline-separated
Returns: dict with 'added' (list), 'already_present' (list), 'dnsbl_status', and 'service_status'.
Inputs: uuid (required), domains (required). Returns: object
opn_add_dnsmasq_rangeA
Create a new dnsmasq DHCP range and apply the configuration.
Use this to add DHCPv4 or DHCPv6 address ranges with optional Router Advertisement (RA) configuration.
Inputs: end_addr (required), interface (required), start_addr (required), ra_mode, +3 more. Returns: object
opn_add_dns_overrideA
Add an Unbound DNS host override (A/AAAA record) and apply immediately.
Use this when you need to create a local DNS record that resolves a hostname to a specific IP address. Useful for split-horizon DNS, internal services, or overriding external DNS for specific hosts.
Changes are applied immediately (Unbound is reconfigured automatically). DNS overrides cannot be auto-reverted — verify settings before calling. Use opn_list_dns_overrides to check existing overrides first.
Parameters:
hostname: the hostname part (e.g. 'myserver')
domain: the domain part (e.g. 'local.lan')
server: the IP address to resolve to (IPv4 or IPv6)
description: optional description
Returns: dict with 'result', 'uuid', 'hostname', 'server', and 'applied' status.
Inputs: domain (required), server (required), hostname (required), description. Returns: object
opn_add_firewall_categoryA
Create a new firewall rule category.
Use this when you need to create a category for organizing firewall rules. Categories are metadata — creating one does not affect traffic or rules.
Parameters:
name: category name (1-255 chars, no commas)
color: hex color code without '#' (e.g. 'ff0000' for red, default '000000')
Returns: dict with 'result' (str), 'uuid' (str), and 'name' (str).
Inputs: name (required), color. Returns: object
opn_add_firewall_ruleA
Create a new MVC firewall filter rule with savepoint protection where supported.
Use this when you need to add a firewall rule.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
IMPORTANT: This creates MVC rules (Settings > Firewall > Automation), not legacy GUI rules.
Parameters:
action: 'pass', 'block', or 'reject'
direction: 'in' or 'out'
interface: interface name (e.g. 'lan', 'wan', 'opt1')
ip_protocol: 'inet' (IPv4), 'inet6' (IPv6), or 'inet46' (dual-stack)
protocol: 'any', 'TCP', 'UDP', 'TCP/UDP', 'ICMP', etc.
source_net: source address/network or 'any'
source_not: invert source match (True = NOT source_net)
source_port: source port number or range, or empty for any
destination_net: destination address/network or 'any'
destination_not: invert destination match (True = NOT destination_net, e.g. !Private_Networks)
destination_port: port number or range (e.g. '80', '1000-2000'), or empty for any
gateway: force traffic via specific gateway (e.g. 'WAN_GW') for policy routing, or empty for default
log: enable logging for this rule (default: off)
quick: first-match wins (default: True). Set False for last-match-wins logic
sequence: rule ordering within priority group (default: 1, higher = later)
categories: comma-separated category UUIDs to assign to this rule
description: human-readable rule description
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: log, quick, action, gateway, +13 more. Returns: object
opn_add_icmpv6_rulesA
Create essential ICMPv6 firewall rules required for IPv6 operation.
Use this when setting up IPv6 on an interface. ICMPv6 is MANDATORY for IPv6 — without it, Neighbor Discovery (NDP), Router Advertisements (RA), and Path MTU Discovery (PMTUD) all break.
Creates 5 rules per RFC 4890:
NDP Neighbor Solicitation (link-local -> multicast)
NDP Neighbor Advertisement (link-local -> any)
NDP Router Solicitation (link-local -> all-routers multicast)
NDP Router Advertisement (link-local -> all-nodes multicast)
ICMPv6 Echo (ping6) inbound
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
Parameters:
interface: target interface (e.g. 'lan', 'opt1', 'opt2')
Returns: dict with 'revision' (str), 'rules' (list of created UUIDs), and instructions to confirm.
Inputs: interface. Returns: object
opn_add_nat_ruleA
Create a NAT port forwarding rule with savepoint protection where supported.
Use this when you need to forward an external port to an internal host. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
Parameters:
destination_port: external port to forward (e.g. '8080', '3000-3010') — required
target_ip: internal IP address to forward to (e.g. '192.168.1.100') — required
interface: source interface (default 'wan')
protocol: 'TCP', 'UDP', or 'TCP/UDP' (default 'TCP')
target_port: internal port (default: same as destination_port)
description: human-readable description
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: protocol, interface, target_ip, description, +2 more. Returns: object
opn_arp_tableA
Get the ARP table showing IP-to-MAC address mappings.
Use this when you need to find which MAC address is associated with an IP, identify devices on a network segment, or troubleshoot connectivity. Returns: dict with 'rows' (list of ARP entries including ip, mac, intf, and hostname fields) and 'rowCount' (total).
Inputs: no named parameters. Returns: object
opn_configure_mdns_repeaterA
Enable and configure the mDNS Repeater to relay multicast DNS between interfaces.
Use this to set up cross-VLAN mDNS discovery. The repeater relays mDNS packets (224.0.0.251:5353) between selected interfaces, enabling HomeKit, Chromecast, AirPlay, and other mDNS-based device discovery across VLANs.
Inputs: enabled, interfaces. Returns: object
opn_confirm_changesA
Confirm pending firewall changes, cancelling the 60-second auto-rollback.
Use this AFTER applying firewall changes (rule add/edit/delete) to make them permanent. If not called within 60 seconds of applying, OPNsense automatically reverts all changes for safety.
Only relevant on OPNsense < 26.7. Newer versions have no savepoint API; there the write tools return an empty revision and this call is a no-op. Returns: dict with confirmation status, or status 'not_applicable'.
Inputs: revision (required). Returns: object
opn_crowdsec_alertsA
List CrowdSec security alerts (detected threats and attacks).
Use this when you need to review security events detected by CrowdSec, including brute-force attempts, port scans, and other threats. Note: Requires the CrowdSec plugin (os-crowdsec). Returns: dict with 'rows' (list of alerts) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_crowdsec_statusA
Get CrowdSec security engine status and active decisions summary.
Use this when you need to check if CrowdSec is running, see how many active security decisions (bans/captchas) are in effect, and get a quick overview of the threat protection state. Note: Requires the CrowdSec plugin (os-crowdsec). Returns: dict with 'service_status', 'decisions_count', and 'alerts_count'.
Inputs: no named parameters. Returns: object
opn_delete_aliasA
Delete a firewall alias by UUID.
IMPORTANT: Check if any firewall rules reference this alias BEFORE deleting. Deleting an alias that is referenced by rules may cause those rules to stop matching traffic. Use opn_list_firewall_rules to check for references first.
This does NOT use savepoint protection — aliases are metadata definitions. The deletion takes effect immediately.
Use opn_list_firewall_aliases first to find the UUID. Returns: dict with 'result' (str) and 'uuid' (str).
Inputs: uuid (required). Returns: object
opn_delete_ddns_accountA
Delete a Dynamic DNS account by UUID and apply the configuration.
The deletion is applied immediately (ddclient is reconfigured automatically). Use opn_list_ddns_accounts first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required). Returns: object
opn_delete_dnsmasq_rangeA
Delete a dnsmasq DHCP range by UUID and apply the configuration.
The deletion is applied immediately (dnsmasq is reconfigured automatically). Use opn_list_dnsmasq_ranges first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required). Returns: object
opn_delete_dns_overrideA
Delete an Unbound DNS host override by UUID and apply immediately.
The deletion is applied immediately (Unbound is reconfigured automatically). DNS changes cannot be auto-reverted — verify the UUID before calling. Use opn_list_dns_overrides first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'applied' status.
Inputs: uuid (required). Returns: object
opn_delete_firewall_categoryA
Delete a firewall rule category by UUID with savepoint protection where supported.
IMPORTANT: Reassign rules to other categories BEFORE deleting to avoid orphaned category references. Use opn_list_firewall_categories to find categories and opn_set_rule_categories to reassign rules first.
System default categories (auto=1) cannot be deleted. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Returns: dict with 'revision' (str) for confirming and 'result' (str).
Inputs: uuid (required). Returns: object
opn_delete_firewall_ruleA
Delete a firewall filter rule by UUID with savepoint protection where supported.
Use this when you need to remove an existing MVC firewall rule.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID of the rule to delete. Returns: dict with 'revision' (str) for confirming and 'result' (str).
Inputs: uuid (required). Returns: object
opn_delete_nat_ruleA
Delete a NAT port forwarding rule by UUID with savepoint protection where supported.
Use this when you need to remove an existing NAT rule.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_nat_rules first to find the UUID of the rule to delete. Returns: dict with 'revision' (str) for confirming and 'result' (str).
Inputs: uuid (required). Returns: object
opn_dns_lookupA
Perform a DNS lookup from the OPNsense firewall.
Use this when you need to test DNS resolution from the firewall's perspective, verify Unbound is resolving correctly, or check if a specific DNS server returns expected results. Returns: dict with 'result' (str) and 'response' (DNS query results).
Inputs: hostname (required), server. Returns: object
opn_dns_statsA
Get Unbound DNS resolver statistics (queries, cache hits, uptime).
Use this when you need to check DNS resolver performance, cache hit rates, or troubleshoot DNS resolution issues. Returns: dict with resolver statistics fields.
Inputs: no named parameters. Returns: object
opn_download_configA
Download OPNsense config.xml backup as raw XML.
Use this ONLY when you need a full XML backup for archival purposes. For analyzing specific config sections, use opn_scan_config to build a cached inventory, then opn_get_config_section to query individual sections.
By default, sensitive data (passwords, keys, secrets) is redacted; a config that cannot be parsed for redaction is refused, never returned raw. include_sensitive=true additionally requires OPNSENSE_ALLOW_SENSITIVE=true in the server environment — without it, the call is refused. Returns: dict with 'config_xml' (str), 'stripped' (bool), 'size_bytes' (int), or 'error'/'error_type' when the config cannot be parsed.
Inputs: include_sensitive. Returns: object
opn_firewall_logA
Get recent firewall log entries (blocked and passed packets).
Use this when you need to check what traffic has been blocked or passed, troubleshoot connectivity issues, or audit firewall activity. All filter parameters are optional substring matches applied client-side. Returns: dict with 'entries' (list of log rows) and 'total' (count after filtering).
Inputs: limit, action, interface, source_ip, +1 more. Returns: object
opn_gateway_statusA
Get gateway status including dpinger health checks.
Use this when you need to check if WAN gateways are up, their latency, packet loss, or failover state. Returns: dict with gateway items including status, loss, and delay fields. (If the API answers with a bare array, it arrives wrapped in the 'rows'/'rowCount' envelope.)
Inputs: no named parameters. Returns: object
opn_get_config_sectionA
Get a specific configuration section as structured JSON.
Use this after opn_scan_config to drill into a specific area of the OPNsense configuration. If the config hasn't been scanned yet, it will be loaded automatically.
Available sections vary by OPNsense installation. Common sections include: system, interfaces, vlans, filter (legacy firewall rules), nat, OPNsense (MVC plugin config), unbound, dnsmasq, dhcpd, staticroutes, syslog.
The 'filter' section is particularly useful — it contains legacy GUI firewall rules that are NOT visible via opn_list_firewall_rules.
Sensitive values are redacted by default; include_sensitive=true requires OPNSENSE_ALLOW_SENSITIVE=true in the server environment. Returns: dict with 'section' name and 'data' (structured config data).
Inputs: section (required), include_sensitive. Returns: object
opn_get_dnsblA
Get full DNSBL configuration for a specific blocklist by UUID.
Use this when you need to see all available providers and their selection state, current allowlist/blocklist entries, and other DNSBL settings. Get the UUID from opn_list_dnsbl first.
Returns: dict with 'selected_providers', 'available_providers', 'allowlists', 'blocklists', 'wildcards', and config fields.
Inputs: uuid (required). Returns: object
opn_haproxy_addA
Create a new HAProxy resource.
Use this to add frontends, backends, servers, actions, ACLs, health checks, error files, resolvers, or mailers.
The config dict contains field name-value pairs. Only specify fields you want to set — the API fills in defaults for omitted fields.
Health check example:
config={"name": "hc_web", "type": "http", "interval": "5000", "checkport": "8080", "http_method": "get", "http_uri": "/", "http_version": "http11"}
For apps returning non-2xx (e.g. 401 behind auth), add: "http_expressionEnabled": "1", "http_expression": "rstatus", "http_value": "^[2-4][0-9]{2}$"
After creating, link to a backend with opn_haproxy_update: config={"healthCheck": ""}
IPv6 examples:
Frontend bind: config={"name": "web-v6", "bind": "[::]:443,0.0.0.0:443", "mode": "http", "ssl_enabled": "1", "defaultBackend": ""}
Server address: config={"name": "srv1", "address": "2001:db8::1", "port": "8080"}
Backend resolvePrefer: config={"name": "pool1", "mode": "http", "algorithm": "roundrobin", "resolvePrefer": "ipv6"}
NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy. Call opn_haproxy_configtest first to validate the configuration.
Returns: dict with 'result' (str) and 'uuid' (str) of the new resource.
Inputs: config (required), resource_type (required). Returns: object
opn_haproxy_configtestA
Validate HAProxy configuration syntax before applying.
Use this BEFORE calling opn_reconfigure_haproxy to verify the configuration is valid. This runs 'haproxy -c' internally and reports any syntax errors.
Returns: dict with validation result (typically 'status' key).
Inputs: no named parameters. Returns: object
opn_haproxy_deleteA
Delete a HAProxy resource by UUID.
IMPORTANT: Check for dependencies before deleting:
Delete servers before deleting backends that reference them
Delete actions/ACLs before deleting frontends/backends that link them
Delete backends before deleting frontends that use them as defaultBackend
Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.
NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy.
Returns: dict with 'result' indicating success.
Inputs: uuid (required), resource_type (required). Returns: object
opn_haproxy_getA
Get detailed configuration for a specific HAProxy resource.
Use this to inspect all fields of a single resource before modifying it. Returns the full field set including SSL, tuning, persistence, and linked resources.
Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.
Returns: dict with the resource type as key containing all field values.
Inputs: uuid (required), resource_type (required). Returns: object
opn_haproxy_searchA
Search HAProxy resources by type.
Use this to list and search any HAProxy resource. All resource types use the same paginated search pattern.
Resource types and their key fields:
frontends: name, bind (IPv6: [::]:443), mode (http/ssl/tcp), ssl_enabled, defaultBackend
backends: name, mode, algorithm (roundrobin/leastconn/source), linkedServers, healthCheck
servers: name, address (IPv4/IPv6), port, mode (active/backup/disabled), weight, ssl
actions: name, testType, operator (AND/OR), linkedAcls, useBackend
acls: name, expression, negate
healthchecks: name, type (http/tcp/agent/ldap/mysql/pgsql/redis/smtp), interval
errorfiles: name, code (HTTP status), content
resolvers: name, nameserver, timeout
mailers: name, mailserver, port
Returns: dict with 'rows' (list of resources) and 'rowCount' (total).
Inputs: resource_type (required), limit, search. Returns: object
opn_haproxy_statusA
Get HAProxy load balancer status and backend health.
Use this when you need to check HAProxy server status, backend availability, or connection statistics. Note: Requires the HAProxy plugin (os-haproxy). Returns: dict with HAProxy status including servers and backends.
Inputs: no named parameters. Returns: object
opn_haproxy_updateA
Update an existing HAProxy resource.
Use this to modify any field on a HAProxy resource. Only provide the fields you want to change — omitted fields keep their current values.
To enable/disable a resource, set config={"enabled": "1"} or {"enabled": "0"}.
Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.
NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy. Call opn_haproxy_configtest first to validate the configuration.
Returns: dict with 'result' indicating success.
Inputs: uuid (required), config (required), resource_type (required). Returns: object
opn_interface_statsA
Get per-interface traffic statistics (bytes in/out, packets, errors).
Use this when you need to see network utilization, check for interface errors, or compare traffic across interfaces. Returns: dict with 'statistics' (per-interface counters keyed by interface label).
Inputs: no named parameters. Returns: object
opn_ipsec_statusA
Get IPsec VPN tunnel status (IKE and ESP phases).
Use this when you need to check IPsec site-to-site tunnel health, see connected peers, or troubleshoot VPN connectivity. Shows both Phase 1 (IKE negotiation) and Phase 2 (ESP/AH tunnels). Note: Requires IPsec to be configured. Based on strongSwan (OPNsense 23.1+). Returns: dict with 'service_status', 'phase1' (IKE sessions), and 'phase2' (tunnels).
Inputs: no named parameters. Returns: object
opn_ipv6_statusA
Get IPv6 configuration and address status for all interfaces.
Use this when you need a quick overview of which interfaces have IPv6 configured, what addresses are assigned, and the IPv6 method (DHCPv6-PD, Track Interface, SLAAC, static).
Returns: dict with 'interfaces' (list of per-interface IPv6 info) and 'summary' (counts of configured/unconfigured interfaces).
Inputs: no named parameters. Returns: object
opn_list_acme_certsA
List ACME (Let's Encrypt) certificates and their status.
Use this when you need to check certificate expiry dates, renewal status, or which domains have ACME certificates configured. Note: Requires the ACME client plugin (os-acme-client). Returns: dict with 'rows' (list of certificates) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_cron_jobsA
List scheduled cron jobs configured in OPNsense.
Use this when you need to check what scheduled tasks are configured, their frequency, or which commands they run. Returns: dict with 'rows' (list of cron jobs) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_ddns_accountsA
List Dynamic DNS (DDNS) accounts and their update status.
Use this to check which hostnames have DDNS configured, their current IP addresses, last update time, and which service provider is used.
Key fields: service (provider), hostname, checkip (method), current_ip, current_mtime (last update), interface, enabled.
For IPv6 DDNS: the global setting 'allowipv6' must be enabled AND an IPv6-capable checkip method must be used (e.g. 'cloudflare-ipv6'). Both must be set or IPv6 updates silently fail.
Note: Requires the Dynamic DNS plugin (os-ddclient). Returns: dict with 'rows' (list of accounts) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dhcp_leasesA
List current DHCPv4 leases from the ISC DHCP server (legacy).
Use this when the OPNsense instance uses the ISC DHCP plugin (os-isc-dhcp). ISC DHCP is legacy and being phased out — most 26.x instances use dnsmasq or Kea. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with DHCP lease entries including address, mac, and hostname fields. (If the API answers with a bare array, it arrives wrapped in the 'rows'/'rowCount' envelope.)
Inputs: no named parameters. Returns: object
opn_list_dnsblA
List DNSBL (DNS Blocklist) configurations with providers and status.
Use this when you need to see which DNS blocklists are configured, which providers are active, and what allowlist/blocklist entries exist. Use opn_get_dnsbl with a UUID from the results for full details. Returns: dict with 'rows' (list of blocklist configs) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dns_forwardsA
List Unbound DNS forward zones (domain-specific DNS servers).
Use this when you need to check which domains are forwarded to specific upstream DNS servers or DNS-over-TLS resolvers. Returns: dict with 'rows' (list of forward zones) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dnsmasq_leasesA
List current DHCPv4 and DHCPv6 leases from the dnsmasq DNS/DHCP server.
Use this when the OPNsense instance uses dnsmasq for DHCP (default in 26.x). dnsmasq is a lightweight combined DNS/DHCP server that handles both DHCPv4 and DHCPv6. IPv6 leases appear alongside IPv4 leases in the results. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with 'rows' (list of leases) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dnsmasq_rangesA
List dnsmasq DHCP ranges (both DHCPv4 and DHCPv6 with RA config).
Use this to see configured DHCP address pools and Router Advertisement settings for each interface. Both IPv4 and IPv6 ranges appear in the same list.
Key fields: interface, start_addr, end_addr, prefix_len (IPv6) or subnet_mask (IPv4), ra_mode (slaac/ra-stateless/ra-only), ra_priority, lease_time, enabled.
Note: Requires the dnsmasq DNS/DHCP server (os-dnsmasq-dns or built-in). Returns: dict with 'rows' (list of ranges) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dns_overridesB
List Unbound DNS host overrides (local DNS records).
Use this when you need to see which hostnames are overridden to specific IP addresses in the local DNS resolver. Returns: dict with 'rows' (list of overrides) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_firewall_aliasesA
List firewall alias definitions (IP lists, port groups, GeoIP, URLs).
Use this when you need to see which aliases are defined, their types, or what IP addresses/networks they resolve to. Returns: dict with 'rows' (list of aliases) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_firewall_categoriesA
List firewall rule categories.
Use this when you need to see which categories exist, check their names and colors, or find category UUIDs for assigning to rules. Returns: dict with 'rows' (list of categories) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_firewall_rulesA
List firewall filter rules configured via the MVC API.
IMPORTANT: This only returns rules created through the OPNsense MVC filter API (Settings > Firewall > Automation). Legacy rules configured via the traditional GUI (Firewall > Rules) are NOT visible through this endpoint. Most users have legacy rules — a result of 0 rules does not mean no rules exist.
Use this when you need to inspect MVC-managed firewall filter rules. Returns: dict with 'rows' (list of rules) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_kea_leasesA
List current DHCPv4 leases from the Kea DHCP server.
Use this when the OPNsense instance uses Kea for DHCP (available since 24.7). Kea is the modern replacement for ISC DHCP, recommended for HA setups. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with 'rows' (list of leases) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_nat_rulesA
List NAT port forwarding (DNAT) rules.
Use this when you need to see which ports are forwarded to internal hosts, check NAT rule configuration, or troubleshoot port forwarding issues.
Like firewall filter rules, this only returns MVC-managed NAT rules. Legacy NAT rules from the traditional GUI may not appear here — use opn_get_config_section('nat') to see all NAT configuration.
Returns: dict with 'rows' (list of NAT rules) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_servicesA
List system services and their running status.
Use this when you need to check which services are running, stopped, or available on the OPNsense instance. Returns: dict with 'rows' (list of services) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_static_routesA
List configured static routes.
Use this when you need to see custom routing table entries, check which networks are routed through which gateways, or troubleshoot routing issues. Note: This shows configured static routes, not the full kernel routing table. Returns: dict with 'rows' (list of static routes) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_mcp_infoA
Get MCP server version and runtime configuration.
Use this to check the MCP server version, whether write mode is enabled, the detected OPNsense API version, and whether firewall writes still get savepoint/rollback protection. Version detection runs here if no earlier call triggered it; if the firewall is unreachable, the failure is reported instead of raised. Returns: dict with 'mcp_version', 'write_mode', 'opnsense_version', 'api_style', 'savepoint_support' and, only when detection failed, 'version_detection_error'. 'savepoint_support' is true when the 60-second auto-revert is available, false when OPNsense no longer offers it (26.7+ removed it upstream, so firewall changes are immediate and permanent), and null when no firewall write has probed for it yet.
Inputs: no named parameters. Returns: object
opn_mdns_repeater_statusA
Get mDNS Repeater service status and configuration.
Use this to check if the mDNS Repeater is installed, enabled, running, and which interfaces it is configured to relay multicast DNS between.
The mDNS Repeater relays mDNS (224.0.0.251:5353) packets between selected interfaces, enabling device discovery (HomeKit, Chromecast, AirPlay, etc.) across VLANs.
Note: Requires the mDNS Repeater plugin (os-mdns-repeater). Returns: dict with 'service_running', 'enabled', 'interfaces', 'blocklist'.
Inputs: no named parameters. Returns: object
opn_ndp_tableA
Get the NDP table showing IPv6-to-MAC address mappings.
Use this when you need to find which MAC address is associated with an IPv6 address, identify IPv6-enabled devices on a network segment, or troubleshoot IPv6 neighbor reachability. This is the IPv6 equivalent of the ARP table. Returns: dict with 'rows' (list of NDP entries including ip, mac, intf, and manufacturer fields) and 'rowCount' (total).
Inputs: no named parameters. Returns: object
opn_openvpn_statusA
Get OpenVPN connection status (instances, sessions, routes).
Use this when you need to check OpenVPN server/client status, see connected clients, active VPN routes, or troubleshoot OpenVPN tunnels. Note: OpenVPN is built-in (no plugin needed) but must be configured. Returns: dict with 'instances', 'sessions' (connected clients), and 'routes'.
Inputs: no named parameters. Returns: object
opn_pf_statesA
Query the active PF (packet filter) state table.
Use this when you need to see active connections through the firewall, debug NAT issues, or identify which hosts are communicating. Returns: dict with 'rows' (list of state entries) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_pingA
Ping a host from the OPNsense firewall to test connectivity.
Use this when you need to check if a host is reachable from the firewall, measure round-trip latency, or diagnose network connectivity issues. The ping runs on the firewall itself, not locally. Returns: dict with ping results including loss percentage and RTT stats.
Inputs: host (required), count. Returns: object
opn_reconfigure_ddclientA
Apply pending Dynamic DNS configuration changes.
Use this after manually editing DDNS account settings to apply the changes to the running ddclient service.
Note: opn_add_ddns_account auto-reconfigures, so this is only needed for manual edits or troubleshooting.
Note: Requires the Dynamic DNS plugin (os-ddclient). Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_reconfigure_dnsmasqA
Apply pending dnsmasq DNS/DHCP configuration changes.
Use this after manually editing dnsmasq settings to apply the changes to the running dnsmasq service.
Note: opn_add_dnsmasq_range auto-reconfigures, so this is only needed for manual edits or troubleshooting.
Note: Requires the dnsmasq DNS/DHCP server. Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_reconfigure_haproxyA
Apply pending HAProxy load balancer configuration changes.
Use this after making HAProxy configuration changes to apply them to the running HAProxy service. This reconfigures HAProxy with the new settings.
NOTE: This does not use savepoint protection. HAProxy changes take effect immediately. Requires the HAProxy plugin (os-haproxy). IMPORTANT: Do NOT call haproxy/service/start after reconfigure — reconfigure already starts the service, and start will error if already running. IMPORTANT: Always call opn_haproxy_configtest before reconfiguring to validate the configuration syntax. Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_reconfigure_unboundA
Apply pending Unbound DNS resolver configuration changes.
Use this after making DNS configuration changes (adding overrides, forward zones, etc.) to apply them to the running Unbound service. This restarts Unbound with the new configuration.
NOTE: This does not use savepoint protection. DNS changes take effect immediately and cannot be auto-reverted. Verify settings before calling. Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_remove_dnsbl_allowlistA
Remove domains from a DNSBL allowlist.
Use this when you no longer need a domain allowlisted and want to re-enable DNSBL blocking for it. Changes are applied immediately.
Get the UUID from opn_list_dnsbl first.
Parameters:
uuid: blocklist UUID from opn_list_dnsbl
domains: domains to remove, comma or newline-separated
Returns: dict with 'removed' (list), 'not_found' (list), 'dnsbl_status', and 'service_status'.
Inputs: uuid (required), domains (required). Returns: object
opn_scan_configA
Scan the OPNsense configuration and build a cached inventory.
Use this FIRST when starting a new session. Downloads the full config, parses it into queryable sections, and detects runtime state (services, DHCP backend, DNS servers). Results are cached for the session — subsequent calls return the cached version unless force=True.
Call with force=True to rescan after manual config changes on the firewall. Use opn_get_config_section(section) to drill into specific sections.
Returns: dict with 'firmware', 'plugins', 'dhcp', 'dns', 'interfaces', 'services', and 'config_sections' (list of available sections with sizes).
Inputs: force. Returns: object
opn_security_auditA
Run a comprehensive security audit of the OPNsense firewall.
Checks 11 security areas: firmware, firewall rules (MVC + legacy), NAT/port forwarding, DNS resolver security, system hardening (SSH, HTTPS, syslog), services, certificates, VPN status (incl. WireGuard config audit), HAProxy reverse proxy security, and gateway health.
Findings are tagged with applicable compliance frameworks: PCI DSS v4.0, BSI IT-Grundschutz, NIST SP 800-41, CIS Benchmarks.
Returns a structured audit report with findings categorized by severity (critical, warning, info). Each finding includes a recommendation and applicable compliance framework references.
Use this when you need to assess the security posture of the firewall, identify misconfigurations, or perform a routine health check.
Inputs: no named parameters. Returns: object
opn_set_dnsblA
Update a DNSBL blocklist configuration (read-modify-write).
Use this when you need to change DNSBL settings — providers, allowlists, blocklists, etc. Only the parameters you provide are changed; all other settings are preserved. Changes are applied immediately.
Get the UUID from opn_list_dnsbl first.
Parameters:
uuid: blocklist UUID from opn_list_dnsbl
enabled: enable/disable this blocklist
providers: comma-separated provider shortcodes (e.g. 'hgz002,hgz011,ag')
custom_urls: newline-separated custom blocklist URLs
allowlists: newline-separated allowlist entries (domains or regex patterns)
blocklists: newline-separated custom block domains
wildcards: newline-separated wildcard block domains
source_nets: comma-separated source networks (empty = all)
nxdomain: return NXDOMAIN instead of 0.0.0.0 for blocked domains
cache_ttl: cache TTL in seconds for DNSBL responses
description: human-readable description
Returns: dict with 'result', 'dnsbl_status', and 'service_status'.
Inputs: uuid (required), enabled, nxdomain, cache_ttl, +7 more. Returns: object
opn_set_rule_categoriesA
Assign categories to a firewall rule by UUID with savepoint protection where supported.
Use this when you need to categorize or re-categorize a firewall rule. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
Parameters:
uuid: the firewall rule UUID (from opn_list_firewall_rules)
categories: comma-separated category UUIDs (from opn_list_firewall_categories), or empty string to clear all categories
Returns: dict with 'revision' (str) for confirming and 'uuid' (str).
Inputs: uuid (required), categories. Returns: object
opn_system_statusA
Get OPNsense system status including firmware version and product info.
Use this when you need to check the current firmware version, system name, or verify the OPNsense appliance is reachable and responding. Returns: dict with firmware/product info. On OPNsense 26.x+, product fields are nested under a 'product' key; earlier versions have them at the top level.
Inputs: no named parameters. Returns: object
opn_toggle_aliasA
Toggle a firewall alias's enabled/disabled state.
Use this when you need to temporarily disable an alias without deleting it, or re-enable a previously disabled alias. The toggle flips the current state.
This does NOT use savepoint protection — aliases are metadata definitions. Use opn_list_firewall_aliases first to find the UUID. Returns: dict with 'result' (str) and 'uuid' (str).
Inputs: uuid (required). Returns: object
opn_toggle_firewall_ruleA
Toggle a firewall filter rule's enabled/disabled state with savepoint protection where supported.
Use this when you need to temporarily disable a rule for testing or re-enable a previously disabled rule. The toggle flips the current state.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID of the rule. Returns: dict with 'revision' (str) for confirming and 'uuid' (str).
Inputs: uuid (required). Returns: object
opn_tracerouteB
Trace the network path from OPNsense to a destination host.
Use this when you need to diagnose routing issues, identify where packets are being dropped, or visualize the network hops to a destination. Returns: dict with 'result' (str) and 'response' (list of hops).
Inputs: host (required), protocol, ip_version. Returns: object
opn_update_aliasA
Update an existing firewall alias by UUID (read-modify-write).
Use this when you need to rename an alias, change its content (IPs, networks, ports), modify its description, or change its type. Only the parameters you provide are changed; all other settings are preserved.
This does NOT require savepoint protection — aliases are metadata definitions that only affect traffic when referenced by a firewall rule.
Use opn_list_firewall_aliases first to find the UUID.
Parameters:
uuid: alias UUID (from opn_list_firewall_aliases)
name: new alias name (alphanumeric and underscores only)
content: new alias entries separated by newlines
description: new description
alias_type: new type ('host', 'network', 'port', 'urltable', 'geoip')
enabled: enable/disable the alias
Returns: dict with 'result' (str) and 'uuid' (str).
Inputs: uuid (required), name, content, enabled, +2 more. Returns: object
opn_update_ddns_accountA
Update a Dynamic DNS account by UUID and apply the configuration.
Use this when you need to change the hostname, provider, credentials, or other properties of a DDNS account. Only the parameters you provide are changed; all other settings are preserved.
After update, the ddclient service is automatically reconfigured. Changes take effect immediately. Use opn_list_ddns_accounts first to find the UUID.
Parameters:
uuid: account UUID (from opn_list_ddns_accounts)
service: DDNS provider name (e.g. 'cloudflare', 'dyndns', 'noip')
hostname: fully qualified domain name to update
username: provider username or API key
password: provider password or API token
checkip: IP check method (e.g. 'web_dyndns', 'if')
interface: network interface name (e.g. 'wan')
description: human-readable description
enabled: enable/disable the account
Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required), checkip, enabled, service, +5 more. Returns: object
opn_update_dnsblA
Reload DNSBL blocklist files and restart Unbound to apply them.
Use this when DNSBL lists need to be refreshed without changing the configuration — for example after a service restart that lost loaded lists, or to force Unbound to pick up previously generated blocklist files. This flushes the DNS cache, so previously cached blocked (or unblocked) domains will be re-evaluated.
NOTE: This does not use savepoint protection. DNS changes take effect immediately and cannot be auto-reverted. Returns: dict with 'dnsbl_status' and 'service_status'.
Inputs: no named parameters. Returns: object
opn_update_dnsmasq_rangeA
Update a dnsmasq DHCP range by UUID and apply the configuration.
Use this when you need to change the address range, lease time, RA settings, or other properties. Only the parameters you provide are changed; all other settings are preserved.
After update, the dnsmasq service is automatically reconfigured. Changes take effect immediately. Use opn_list_dnsmasq_ranges first to find the UUID.
Parameters:
uuid: range UUID (from opn_list_dnsmasq_ranges)
interface: network interface name (e.g. 'lan', 'opt1')
start_addr: start of address range
end_addr: end of address range
prefix_len: IPv6 prefix length (e.g. '64')
ra_mode: Router Advertisement mode ('slaac', 'ra-stateless', 'ra-only')
lease_time: lease duration (e.g. '24h', '1h')
description: human-readable description
enabled: enable/disable the range
Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required), enabled, ra_mode, end_addr, +5 more. Returns: object
opn_update_dns_overrideA
Update an Unbound DNS host override by UUID and apply immediately.
Use this when you need to change the hostname, domain, IP address, or other properties of a DNS override. Only the parameters you provide are changed; all other settings are preserved.
Changes are applied immediately (Unbound is reconfigured automatically). DNS overrides cannot be auto-reverted — verify settings before calling. Use opn_list_dns_overrides first to find the UUID.
Parameters:
uuid: override UUID (from opn_list_dns_overrides)
hostname: new hostname part (e.g. 'myserver')
domain: new domain part (e.g. 'local.lan')
server: new IP address (IPv4 or IPv6)
description: new description
enabled: enable/disable the override
Returns: dict with 'result' (str), 'uuid' (str), and 'applied' status.
Inputs: uuid (required), domain, server, enabled, +2 more. Returns: object
opn_update_firewall_ruleA
Update an existing MVC firewall rule by UUID with savepoint protection where supported.
Use this when you need to modify a firewall rule's action, source/destination, protocol, ports, or other properties. Only the parameters you provide are changed; all other settings are preserved.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID.
Parameters:
uuid: rule UUID (from opn_list_firewall_rules)
action: 'pass', 'block', or 'reject'
direction: 'in' or 'out'
interface: interface name (e.g. 'lan', 'wan', 'opt1')
ip_protocol: 'inet' (IPv4), 'inet6' (IPv6), or 'inet46' (dual-stack)
protocol: 'any', 'TCP', 'UDP', 'TCP/UDP', 'ICMP', etc.
source_net: source address/network or 'any'
source_not: invert source match
source_port: source port number or range
destination_net: destination address/network or 'any'
destination_not: invert destination match
destination_port: port number or range
gateway: force traffic via specific gateway, or empty to clear
log: enable/disable logging
quick: first-match wins (True) or last-match-wins (False)
sequence: rule ordering within priority group
categories: comma-separated category UUIDs
description: human-readable rule description
enabled: enable/disable the rule
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: uuid (required), log, quick, action, +15 more. Returns: object
opn_update_nat_ruleA
Update an existing NAT port forwarding rule by UUID with savepoint protection where supported.
Use this when you need to change the target IP, port, or other properties of a NAT rule. Only the parameters you provide are changed; all other settings are preserved.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_nat_rules first to find the UUID.
Parameters:
uuid: NAT rule UUID (from opn_list_nat_rules)
interface: source interface (e.g. 'wan', 'opt1')
protocol: 'TCP', 'UDP', or 'TCP/UDP'
destination_port: external port to forward (e.g. '8080', '3000-3010')
target_ip: internal IP address to forward to
target_port: internal port
description: human-readable description
enabled: enable/disable the rule
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: uuid (required), enabled, protocol, interface, +4 more. Returns: object
opn_wireguard_statusA
Get WireGuard VPN tunnel and peer status.
Use this when you need to check WireGuard tunnel health, peer handshake times, transferred bytes, or endpoint information. Note: Requires the WireGuard plugin (os-wireguard). Returns: dict with tunnel and peer details including endpoints and transfer stats.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 81 tools
Most tools are clearly separated by resource and action, and descriptions explicitly warn about MVC vs legacy firewall rules and backend-specific DHCP lease tools. A few areas remain confusable, especially the three DHCP lease listings, opn_set_dnsbl vs opn_update_dnsbl, and the various HAProxy reconfigure/configtest/status tools.
The opn_ prefix is used throughout and most names follow a predictable action_resource pattern such as opn_list_firewall_rules and opn_add_nat_rule. Minor deviations exist, including HAProxy's resource-first naming, alias singular/plural inconsistency, and opn_update_dnsbl meaning 'reload' rather than update configuration.
81 tools is an extreme number for a single MCP server and far beyond the typical 3-15 well-scoped range. While OPNsense is broad, this surface is large enough to make discovery and correct selection burdensome for an agent.
Core areas such as firewall rules, aliases, NAT, DNS overrides, DNSMasq ranges, DDNS, and HAProxy have substantial CRUD coverage, while several other areas are only partially covered. Static routes, services, cron jobs, ACME certificates, and most VPN configuration are read-only or status-only, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA modular MCP server that provides access to over 2,000 OPNsense firewall management methods through 88 specialized tools. It enables AI assistants to securely manage firewall rules, network interfaces, and system diagnostics using a type-safe TypeScript interface.96MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to manage OPNsense firewall, interfaces, DHCP, DNS, routes, and services via natural language through 42 MCP tools.1MIT
- AlicenseAqualityDmaintenanceEnables interaction with OPNsense firewalls through MCP tools for managing firewall rules, interfaces, DHCP leases, and system monitoring.26MIT
- AlicenseNot gradedqualityCmaintenanceThis MCP server enables AI agents to inspect and modify an OPNsense firewall via natural language, using a compact set of generic tools and a resource registry to cover 96 CRUD operations.17 npmAGPL 3.0