90+ tools covering system info, interfaces, firewall rules, aliases, NAT, DHCP, diagnostics, routes, gateways, Unbound DNS, VPN (WireGuard/OpenVPN/IPsec), firmware/updates, system logs, and certificates
Safety guardrails: write operations disabled by default, dry-run mode, WAN rule blocking, required description prefix
Savepoint workflow: create savepoint → apply → cancel rollback (matches OPNsense official API pattern)
Audit logging: all mutations logged to JSONL

Quick Start

1. Create an OPNsense API key

In OPNsense: System → Access → Users → edit user → add API key. Download the key/secret pair.

Grant only the privileges needed. For read-only use, limit to read privileges. For writes, include firewall, aliases, routes, etc.

2. Install

pip install -e /path/to/opnsense-mcp

Or with the Hermes venv:

/usr/local/lib/hermes-agent/venv/bin/pip install -e /root/opnsense-mcp

3. Configure environment

cp .env.example .env
# Edit .env with your API key, secret, and firewall URL

Variable	Default	Description
`OPNSENSE_URL`	`https://10.77.30.1:40443`	Firewall base URL
`OPNSENSE_API_KEY`	—	API key (required)
`OPNSENSE_API_SECRET`	—	API secret (required)
`OPNSENSE_VERIFY_SSL`	`false`	Verify TLS certificate
`OPNSENSE_ALLOW_WRITES`	`false`	Enable mutating operations
`OPNSENSE_DRY_RUN`	`false`	Log writes without executing
`OPNSENSE_REQUIRE_DESCRIPTION_PREFIX`	`mcp:`	Prefix for new firewall rules
`OPNSENSE_BLOCK_WAN_INBOUND_ANY`	`true`	Block WAN allow-all rules

4. Register with Hermes

hermes mcp add opnsense \
  --command /usr/local/lib/hermes-agent/venv/bin/opnsense-mcp \
  --env OPNSENSE_URL=https://10.77.30.1:40443 \
  --env OPNSENSE_API_KEY=your_key \
  --env OPNSENSE_API_SECRET=your_secret \
  --env OPNSENSE_VERIFY_SSL=false \
  --env OPNSENSE_ALLOW_WRITES=false

Or add to ~/.hermes/config.yaml:

mcp_servers:
  opnsense:
    command: "/usr/local/lib/hermes-agent/venv/bin/opnsense-mcp"
    env:
      OPNSENSE_URL: "https://10.77.30.1:40443"
      OPNSENSE_API_KEY: "your_key"
      OPNSENSE_API_SECRET: "your_secret"
      OPNSENSE_VERIFY_SSL: "false"
      OPNSENSE_ALLOW_WRITES: "false"
    timeout: 120

Restart the Hermes gateway after adding.

5. Test

hermes mcp test opnsense

Or ask Hermes: "Use opnsense_test_connection to verify firewall access"

Tool Categories

Read-only (always available with valid API key)

Tool	Description
`opnsense_test_connection`	Verify API auth and connectivity
`opnsense_get_system_info`	Version, uptime, health
`opnsense_list_interfaces`	Interface status and IPs
`opnsense_search_firewall_rules`	Search filter rules
`opnsense_search_aliases`	Search aliases
`opnsense_search_dhcp_leases`	DHCP lease table
`opnsense_get_arp_table`	ARP / IP→MAC
`opnsense_get_gateway_status`	WAN gateway health
`opnsense_get_firewall_log`	Recent blocked/ passed traffic
`opnsense_get_pf_states`	Active connection states
`opnsense_search_port_forwards`	Port forward rules
`opnsense_search_dns_host_overrides`	Unbound local DNS records
`opnsense_wireguard_status`	WireGuard tunnels and peer handshakes
`opnsense_openvpn_sessions`	Connected OpenVPN clients
`opnsense_ipsec_status`	IPsec service and sessions
`opnsense_firmware_check_updates`	Available updates from mirrors
`opnsense_firmware_audit`	Package vulnerability audit
`opnsense_get_system_log`	Syslog search (system, dhcp, dns, vpn, audit, ...)
`opnsense_list_certificates`	Trust store certificates (no private keys)
`opnsense_get_interface_traffic`	Per-interface traffic rates

Write operations (require `OPNSENSE_ALLOW_WRITES=true`)

Tool	Description
`opnsense_add_firewall_rule`	Add filter rule (prefix required)
`opnsense_toggle_firewall_rule`	Enable/disable rule
`opnsense_create_firewall_savepoint`	Snapshot before changes
`opnsense_apply_firewall`	Apply pending changes
`opnsense_cancel_firewall_rollback`	Confirm changes (cancel 60s rollback)
`opnsense_safe_apply_firewall_rule_change`	Savepoint + toggle + apply workflow
`opnsense_alias_add_entry`	Add IP to alias
`opnsense_add_d_nat_rule`	Add port forward
`opnsense_add_dns_host_override`	Add local DNS record (+ reconfigure)
`opnsense_wireguard_toggle_peer`	Enable/disable WireGuard peer
`opnsense_unbound_restart`	Restart DNS resolver
`opnsense_firmware_update`	Install updates (double confirm)

Safe Change Workflow

1. opnsense_create_firewall_savepoint     → returns revision
2. opnsense_toggle_firewall_rule(uuid)    → make change
3. opnsense_apply_firewall(revision)      → apply with 60s auto-rollback
4. Verify connectivity
5. opnsense_cancel_firewall_rollback(revision)  → keep change

Or use opnsense_safe_apply_firewall_rule_change which combines steps 1–3.

Standalone Usage

Run directly as an MCP stdio server:

OPNSENSE_API_KEY=... OPNSENSE_API_SECRET=... opnsense-mcp

Compatible with Cursor, Claude Desktop, and other MCP clients.

Security Notes

Never commit API keys. Use environment variables or Hermes secrets.
Start with read-only (ALLOW_WRITES=false) until you trust the agent workflows.
Use a dedicated OPNsense user with minimal privileges.
Review audit log at OPNSENSE_AUDIT_LOG_PATH.
Enable Hermes approvals: mode: manual for production use.

License

MIT

README.md Unescape Escape

OPNsense MCP

Features