A secure Model Context Protocol (MCP) server for managing OPNsense firewalls through AI assistants like Claude Code, Cursor, and other MCP-compatible tools.
opnsense-mcp-server is an MCP project maintained in the lucamarien/opnsense-mcp-server repository. The maintainer describes its purpose as “A secure Model Context Protocol (MCP) server for managing OPNsense firewalls through AI assistants like Claude Code, Cursor, and other MCP-compatible tools”. Read the project documentation for the complete scope.
The project provides a local client configuration using opnsense-mcp. Follow the repository’s build and installation steps before copying it, and replace example paths with the paths on your own computer.
The example declares OPNSENSE_URL, OPNSENSE_API_KEY, OPNSENSE_API_SECRET, OPNSENSE_VERIFY_SSL, OPNSENSE_ALLOW_WRITES. Secret-looking values have been replaced with placeholders. Required and optional labels are shown only when the documentation states them.
Project documentation · Repository · Discovery listing. This profile records the public documentation checked on 2026-10-08.
Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.
| Tool | What it does |
|---|---|
| opn_system_status | System info including firmware version, product name, and architecture |
| opn_list_services | List all services and their running status. Params: search, limit |
| opn_gateway_status | Gateway availability, latency, and dpinger health checks |
| opn_download_config | Download config.xml backup with optional sensitive data stripping. Params: include_sensitive (default: false — passwords and keys are redacted) |
| opn_scan_config | Scan the full configuration, parse it into sections, and collect runtime inventory (firmware, plugins, DHCP, DNS, interfaces, services). Results are cached per |
| opn_get_config_section | Get a specific config section as structured JSON. Params: section, include_sensitive |
| opn_mcp_info | MCP server version, write mode status, detected OPNsense version, API style, and whether firewall writes still get savepoint/rollback protection |
| opn_interface_stats | Per-interface traffic statistics (bytes in/out, packets, errors) |
| opn_arp_table | ARP table showing IP-to-MAC address mappings |
| opn_ndp_table | NDP (Neighbor Discovery Protocol) table showing IPv6-to-MAC address mappings |
| opn_ipv6_status | IPv6 configuration and address status for all interfaces (method, live addresses, summary) |
| opn_list_static_routes | Configured static routes. Params: search, limit |
| opn_list_firewall_rules | List MVC firewall filter rules. Params: search, limit |
| opn_list_firewall_aliases | List alias definitions (IP lists, port groups, GeoIP, URLs). Params: search, limit |
| opn_list_nat_rules | List NAT port forwarding (DNAT) rules. Params: search, limit |
| opn_list_firewall_categories | List firewall rule categories and their UUIDs. Params: search, limit |
| opn_firewall_log | Recent firewall log entries with client-side filtering. Params: source_ip, destination_ip, action, interface, limit |
| opn_confirm_changes | Confirm pending changes, cancelling 60-second auto-rollback (OPNsense < 26.7; a no-op returning not_applicable on 26.7+). Params: revision |
| opn_toggle_firewall_rule | Toggle a rule's enabled/disabled state with savepoint (OPNsense < 26.7). Params: uuid |
| opn_add_firewall_rule | Create a new filter rule with savepoint (OPNsense < 26.7). Params: action, direction, interface, ip_protocol, protocol, source_net, destination_net… |
| opn_delete_firewall_rule | Delete a filter rule by UUID with savepoint (OPNsense < 26.7). Params: uuid |
| opn_add_alias | Create a new alias. Params: name, alias_type, content, description |
| opn_add_nat_rule | Create a NAT port forwarding rule with savepoint (OPNsense < 26.7). Params: destination_port, target_ip, interface, protocol, target_port, description |
| opn_add_firewall_category | Create a new firewall rule category. Params: name, color |
| opn_delete_firewall_category | Delete a firewall rule category by UUID with savepoint (OPNsense < 26.7). Params: uuid |
| opn_set_rule_categories | Assign categories to a firewall rule with savepoint (OPNsense < 26.7). Params: uuid, categories |
| opn_add_icmpv6_rules | Create essential ICMPv6 rules required for IPv6 operation (NDP, RA, ping6) per RFC 4890. Params: interface |
| opn_update_alias | Update an existing alias (name, content, type, description). Read-modify-write. Params: uuid, name, content, description, alias_type, enabled |
| opn_delete_alias | Delete an alias by UUID. Check rule references first. Params: uuid |
| opn_toggle_alias | Toggle alias enabled/disabled state. Params: uuid |
| opn_update_firewall_rule | Update filter rule fields with savepoint (OPNsense < 26.7). Params: uuid, action, direction, interface, ip_protocol, protocol, source_net, source_not… |
| opn_update_nat_rule | Update NAT port forwarding rule with savepoint (OPNsense < 26.7). Params: uuid, interface, protocol, destination_port, target_ip, target_port, description… |
| opn_delete_nat_rule | Delete a NAT port forwarding rule by UUID with savepoint (OPNsense < 26.7). Params: uuid |
| opn_list_dns_overrides | Unbound host overrides (local DNS records). Params: search, limit |
| opn_list_dns_forwards | DNS forward zones (domain-specific servers). Params: search, limit |
| opn_dns_stats | Unbound resolver statistics (queries, cache hits, uptime) |
| opn_reconfigure_unbound | Apply pending DNS resolver configuration changes |
| opn_add_dns_override | Add an Unbound DNS host override (A/AAAA record) and apply immediately. Params: hostname, domain, server, description |
| opn_list_dnsbl | List DNSBL blocklist configurations with providers and status. Params: search, limit |
| opn_get_dnsbl | Get full DNSBL configuration by UUID (providers, allowlists, settings). Params: uuid |
| opn_set_dnsbl | Update DNSBL settings (read-modify-write). Params: uuid, enabled, providers, allowlists, blocklists, wildcards, etc. |
| opn_add_dnsbl_allowlist | Add domains to DNSBL allowlist without overwriting. Params: uuid, domains |
| opn_remove_dnsbl_allowlist | Remove domains from DNSBL allowlist. Params: uuid, domains |
| opn_update_dnsbl | Reload DNSBL blocklist files and restart Unbound (no config change, recovery tool) |
| opn_update_dns_override | Update an Unbound DNS host override and apply immediately. Params: uuid, hostname, domain, server, description, enabled |
| opn_delete_dns_override | Delete an Unbound DNS host override and apply immediately. Params: uuid |
| opn_list_dhcp_leases | Active DHCPv4 leases from the ISC DHCP server |
| opn_list_kea_leases | DHCPv4 leases from the Kea DHCP server. Params: search, limit |
| opn_list_dnsmasq_leases | DHCPv4 and DHCPv6 leases from the dnsmasq DNS/DHCP server. Params: search, limit |
| opn_list_dnsmasq_ranges | Configured DHCP address ranges (both DHCPv4 and DHCPv6 with RA config). Params: search, limit |
| opn_add_dnsmasq_range | Create a new DHCP range (IPv4 or IPv6 with Router Advertisement configuration). Params: interface, start_addr, end_addr, prefix_len, ra_mode, lease_time… |
| opn_reconfigure_dnsmasq | Apply pending dnsmasq DNS/DHCP configuration changes |
| opn_update_dnsmasq_range | Update a DHCP range (addresses, lease time, RA config) and apply. Params: uuid, interface, start_addr, end_addr, prefix_len, ra_mode, lease_time… |
| opn_delete_dnsmasq_range | Delete a DHCP range by UUID and apply. Params: uuid |
| opn_wireguard_status | WireGuard tunnel and peer status (requires os-wireguard plugin) |
| opn_ipsec_status | IPsec VPN tunnel status — IKE (Phase 1) and ESP/AH (Phase 2) sessions |
| opn_openvpn_status | OpenVPN connection status — instances, sessions, and routes |
| opn_haproxy_status | HAProxy service status and backend health |
| opn_haproxy_search | Search HAProxy resources by type. Params: resource_type (frontends/backends/servers/actions/acls/healthchecks/errorfiles/resolvers/mailers), search, limit |
| opn_haproxy_get | Get detailed configuration for a specific resource. Params: resource_type, uuid |
| opn_haproxy_configtest | Validate HAProxy configuration syntax before applying |
| opn_haproxy_add | Create a new HAProxy resource. Params: resource_type, config (dict of field values) |
| opn_haproxy_update | Update an existing HAProxy resource (partial updates). Params: resource_type, uuid, config |
| opn_haproxy_delete | Delete a HAProxy resource by UUID. Params: resource_type, uuid |
| opn_reconfigure_haproxy | Apply pending HAProxy configuration changes |
| opn_list_acme_certs | ACME/Let's Encrypt certificates and their status. Params: search, limit |
| opn_list_cron_jobs | Scheduled cron jobs. Params: search, limit |
| opn_crowdsec_status | CrowdSec security engine status and active decisions |
| opn_crowdsec_alerts | CrowdSec security alerts (detected threats). Params: search, limit |
| opn_list_ddns_accounts | Dynamic DNS accounts and their update status. Params: search, limit |
| opn_add_ddns_account | Create a new Dynamic DNS account. Params: service, hostname, username, password, checkip, interface, description |
| opn_reconfigure_ddclient | Apply pending Dynamic DNS configuration changes |
| opn_update_ddns_account | Update a Dynamic DNS account (password is write-only). Params: uuid, service, hostname, username, password, checkip, interface, description, enabled |
| opn_delete_ddns_account | Delete a Dynamic DNS account by UUID. Params: uuid |
| opn_mdns_repeater_status | mDNS Repeater status and configuration (enabled, interfaces, blocklist). Requires os-mdns-repeater plugin |
| opn_configure_mdns_repeater | Configure mDNS Repeater for cross-VLAN device discovery (HomeKit, Chromecast, AirPlay). Params: enabled, interfaces |
| opn_ping | Ping a host from the firewall to test connectivity. Params: host, count (1-10, default 3) |
| opn_traceroute | Trace network path to a destination. Params: host, protocol (ICMP/UDP/TCP), ip_version (4/6) |
| opn_dns_lookup | DNS lookup from the firewall. Params: hostname, server (optional custom DNS server) |
| opn_pf_states | Query active PF state table. Params: search, limit (max 1000) |
| opn_security_audit | Comprehensive 11-area security audit: firmware, firewall rules (MVC + legacy, port grouping, insecure protocols), NAT forwarding, DNS security (DNSSEC, DoT)… |
{
"mcpServers": {
"opnsense": {
"command": "opnsense-mcp",
"env": {
"OPNSENSE_URL": "https://192.168.1.1/api",
"OPNSENSE_API_KEY": "YOUR_OPNSENSE_API_KEY",
"OPNSENSE_API_SECRET": "YOUR_OPNSENSE_API_SECRET",
"OPNSENSE_VERIFY_SSL": "false",
"OPNSENSE_ALLOW_WRITES": "false"
}
}
}
}From the project documentation. Replace placeholders and example paths before connecting.
| Variable | Description | Required |
|---|---|---|
| OPNSENSE_URL | Declared in the maintainer’s client configuration. | Yes |
| OPNSENSE_API_KEY | Declared in the maintainer’s client configuration. | Yes |
| OPNSENSE_API_SECRET | Declared in the maintainer’s client configuration. | Yes |
| OPNSENSE_VERIFY_SSL | Declared in the maintainer’s client configuration. | Check documentation |
| OPNSENSE_ALLOW_WRITES | Declared in the maintainer’s client configuration. | Check documentation |
Stop letting your assistant hallucinate n8n node parameters — this server hands it the real schemas, templates and validation.
AWS Labs' official server suite — current AWS docs, CDK guidance, cost analysis and service tools.
Cloud browsers for AI agents — automation sessions that run in Browserbase's fleet, not on your machine.
Workers, KV, R2 and D1 by conversation — Cloudflare's official remote servers for building and observability.
Dashboards, Prometheus and Loki queries, incidents and alerts — observability by conversation.
kubectl with a conversational interface — inspect pods, read logs, diagnose clusters and manage workloads.