LABSCO SUMMARY

It reaches the parts of OPNsense the API leaves out, which is where the hard problems are.

Outbound NAT, DMZ routing and packet-filter inspection are exactly the things an API-only integration cannot touch, and they are the things that break inter-VLAN traffic; here they run over SSH alongside the API tools, so a diagnosis and its fix happen in one session. Two things to weigh before pointing it at a live firewall: SSH access means shell execution on the box, so the credential you give it is as powerful as the account behind it, and the plan-then-apply and macro-recording paths are the safer way to make a multi-step change than issuing the calls one at a time and hoping.

What it is

A wide operations surface for an OPNsense firewall, working two ways: the OPNsense API for most configuration, and SSH into the box for the parts that need direct XML or shell access, such as outbound NAT and routing repair.

What you get

Firewall rules created, listed, read, updated, toggled and deleted, with find_firewall_rules for locating one and create_firewall_preset for common shapes
VLANs created, listed, read, updated and deleted, and interfaces listed, read and reconfigured — including inter-VLAN routing and DMZ setup
NAT handled through its own family: port forwards and outbound rules created, listed and deleted, nat_get_mode and nat_set_mode switching between automatic, hybrid, manual and disabled, and nat_analyze_config plus nat_apply_changes around them
Routing diagnostics and repair — routing_diagnostics, routing_create_intervlan_rules, routing_fix_dmz and routing_fix_all
Network visibility: list_dhcp_leases, list_arp_entries with lookups by IP, MAC, hostname or interface, get_arp_stats, and device lookups by name, MAC, VLAN or interface, including get_guest_devices
DNS blocklisting: block_domain and block_multiple_domains, unblock_domain, list and search the blocklist, toggle single entries, and subscribe to blocklist categories with add_dnsbl_subscription and apply_blocklist_category
HAProxy managed in full — frontends, backends, servers, ACLs, actions and certificates created, updated and deleted, with haproxy_backend_health, haproxy_stats and haproxy_service_control
ACME certificates signed, renewed, revoked and updated, with its own actions and settings
Monit monitoring: services, tests and alerts added, updated and deleted, plus monit_status
SSH and CLI execution for what the API will not do — ssh_execute, ssh_batch_execute, ssh_show_routing, ssh_show_pf_rules, ssh_system_status, ssh_reload_firewall and targeted fixes such as ssh_fix_dmz_routing
Configuration backups created, listed and restored, with ssh_backup_config and ssh_restore_config as the shell-side equivalent
Macros: start and stop recording a sequence of calls, replay it, export or import it, analyse it, and turn a recorded macro into a tool of its own
An infrastructure-as-code path — iac_list_resource_types, iac_plan_deployment, iac_apply_deployment and iac_destroy_deployment — so a change can be planned before it is applied
test_connection and configure for checking and setting up the connection itself

Requirements

An OPNsense firewall — v24.7 or later recommended — and API credentials: OPNSENSE_HOST, OPNSENSE_API_KEY and OPNSENSE_API_SECRET, with OPNSENSE_VERIFY_SSL for self-signed certificates. Node.js 18+ or Bun 1.0+, installed as npm install -g opnsense-mcp-server. The SSH and CLI tools need separate access — OPNSENSE_SSH_HOST and OPNSENSE_SSH_USERNAME with either OPNSENSE_SSH_PASSWORD or OPNSENSE_SSH_KEY_PATH — and NAT management in particular runs through SSH rather than the API. MIT.

Setup effort

One command plus a key — npm install -g opnsense-mcp-server, then supply credentials

See installation options

USE CASES

01

Working out why one VLAN cannot reach another

Run the routing diagnostics, look at the rules and interface configuration involved, and apply the inter-VLAN fix when the cause is clear.

routing_diagnosticslist_firewall_rulesinterface_get_configrouting_create_intervlan_rules

02

Finding out what is actually on the network right now

Read the DHCP leases and ARP table, then look a device up by MAC, hostname or VLAN.

list_dhcp_leaseslist_arp_entriesfind_device_by_macfind_devices_on_vlan

03

Standing up a new segment

Create the VLAN, configure the interface on it, and add the rules that decide what it may reach.

create_vlaninterface_update_configcreate_firewall_rule

04

Fixing NAT that is breaking a DMZ

Look at the current NAT mode and outbound rules, analyse the configuration, and apply the correction — this path runs over SSH rather than the API.

nat_get_modenat_list_outboundnat_analyze_confignat_fix_dmz

05

Blocking a category of domains across the network

Subscribe to the blocklist category, apply it, and check what a specific domain resolves against afterwards.

list_available_dnsbladd_dnsbl_subscriptionapply_blocklist_categorysearch_dns_blocklist

06

Publishing a new internal service through HAProxy

Create the backend and its servers, put a frontend in front with the certificate, and check the backend reports healthy.

haproxy_backend_createhaproxy_server_addhaproxy_frontend_createhaproxy_backend_health

07

Making a risky change with a way back

Take a configuration backup, plan the deployment before applying it, and restore if the result is wrong.

create_backupiac_plan_deploymentiac_apply_deploymentrestore_backup

08

Turning a fiddly sequence into something repeatable

Record the calls once, replay them on the next firewall, and export the macro — or generate a tool from it.

macro_start_recordingmacro_stop_recordingmacro_playmacro_generate_tool

144 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`acme_add_action`

Create a new ACME automation action (restart HAProxy, restart web UI, SFTP upload, SSH command, etc.)

BEFORE YOU INSTALL

What to know first

Tools you get

144 tools when we connected. Many documented example names are wrong: firewall_list_rules is really list_firewall_rules, vlan_create is create_vlan, backup_create is create_backup, and system_execute_command is cli_execute or ssh_execute.

Requires

npx on PATH
Node.js 18+
OPNSENSE_API_KEY in your environment
OPNSENSE_API_SECRET in your environment

CONTEXT COST

Heavy Standing cost

Rated by the size of the 144 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

TERMINAL

npm install -g opnsense-mcp-server

MCP Clients

Claude Desktop — npx

CLAUDE DESKTOP — NPX · JSON

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": [
        "opnsense-mcp-server"
      ],
      "env": {
        "OPNSENSE_HOST": "https://<YOUR_OPNSENSE>:port",
        "OPNSENSE_API_KEY": "<YOUR_OPNSENSE_API_KEY>",
        "OPNSENSE_API_SECRET": "<YOUR_OPNSENSE_API_SECRET>",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Desktop — Bun

CLAUDE DESKTOP — BUN · JSON

{
  "mcpServers": {
    "opnsense": {
      "command": "bun",
      "args": [
        "run",
        "<YOUR_PATH_TO_OPN_SENSE_MCP>/src/index.ts"
      ],
      "env": {
        "OPNSENSE_HOST": "https://<YOUR_OPNSENSE>:port",
        "OPNSENSE_API_KEY": "<YOUR_OPNSENSE_API_KEY>",
        "OPNSENSE_API_SECRET": "<YOUR_OPNSENSE_API_SECRET>",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

Any MCP client — global install

ANY MCP CLIENT — GLOBAL INSTALL

opnsense-mcp-server

OPNsense MCP Server by vespo92

It reaches the parts of OPNsense the API leaves out, which is where the hard problems are.

What it is

What you get

Requirements

Setup effort

Working out why one VLAN cannot reach another

Finding out what is actually on the network right now

Standing up a new segment

Fixing NAT that is breaking a DMZ

Blocking a category of domains across the network

Publishing a new internal service through HAProxy

Making a risky change with a way back

Turning a fiddly sequence into something repeatable

144 tools

acme_add_action

acme_delete_action

acme_get_settings

acme_renew_certificate

acme_revoke_certificate

acme_sign_certificate

acme_update_certificate

add_dnsbl_subscription

apply_blocklist_category

block_domain

block_multiple_domains

cli_apply_changes

cli_check_nfs

cli_execute

cli_fix_dmz_routing

cli_fix_interface_blocking

cli_reload_firewall

cli_show_routing

configure

create_backup

create_firewall_preset

create_firewall_rule

create_vlan

delete_firewall_rule

delete_vlan

find_arp_by_hostname

find_arp_by_interface

find_arp_by_ip

find_arp_by_mac

find_device_by_mac

find_device_by_name

find_devices_on_vlan

find_firewall_rules

get_arp_stats

get_devices_by_interface

get_firewall_rule

get_guest_devices

get_interfaces

get_vlan

haproxy_acl_create

haproxy_acl_delete

haproxy_acl_update

haproxy_action_create

haproxy_action_delete

haproxy_action_update

haproxy_backend_create

haproxy_backend_delete

haproxy_backend_get

haproxy_backend_health

haproxy_backend_list

haproxy_backend_update

haproxy_certificate_create

haproxy_certificate_list

haproxy_frontend_create

haproxy_frontend_delete

haproxy_frontend_get

haproxy_frontend_list

haproxy_frontend_update

haproxy_server_add

haproxy_server_delete

haproxy_server_update

haproxy_service_control

haproxy_stats

iac_apply_deployment

iac_destroy_deployment

`acme_add_action`

`acme_delete_action`

`acme_get_settings`

`acme_renew_certificate`

`acme_revoke_certificate`

`acme_sign_certificate`

`acme_update_certificate`

`add_dnsbl_subscription`

`apply_blocklist_category`

`block_domain`

`block_multiple_domains`

`cli_apply_changes`

`cli_check_nfs`

`cli_execute`

`cli_fix_dmz_routing`

`cli_fix_interface_blocking`

`cli_reload_firewall`

`cli_show_routing`

`configure`

`create_backup`

`create_firewall_preset`

`create_firewall_rule`

`create_vlan`

`delete_firewall_rule`

`delete_vlan`

`find_arp_by_hostname`

`find_arp_by_interface`

`find_arp_by_ip`

`find_arp_by_mac`

`find_device_by_mac`

`find_device_by_name`

`find_devices_on_vlan`

`find_firewall_rules`

`get_arp_stats`

`get_devices_by_interface`

`get_firewall_rule`

`get_guest_devices`

`get_interfaces`

`get_vlan`

`haproxy_acl_create`

`haproxy_acl_delete`

`haproxy_acl_update`

`haproxy_action_create`

`haproxy_action_delete`

`haproxy_action_update`

`haproxy_backend_create`

`haproxy_backend_delete`

`haproxy_backend_get`

`haproxy_backend_health`

`haproxy_backend_list`

`haproxy_backend_update`

`haproxy_certificate_create`

`haproxy_certificate_list`

`haproxy_frontend_create`

`haproxy_frontend_delete`

`haproxy_frontend_get`

`haproxy_frontend_list`

`haproxy_frontend_update`

`haproxy_server_add`

`haproxy_server_delete`

`haproxy_server_update`

`haproxy_service_control`

`haproxy_stats`

`iac_apply_deployment`

`iac_destroy_deployment`

`iac_list_resource_types`

`iac_plan_deployment`

`interface_configure_dmz`

`interface_enable_intervlan_all`

`interface_enable_intervlan_routing`

`interface_get_config`

`interface_list_overview`

`interface_update_config`

`list_arp_entries`

`list_available_dnsbl`

`list_backups`

`list_dhcp_leases`

`list_dns_blocklist`

`list_firewall_rules`

`list_vlans`