opnsense-mcp/README.md

OPNsense MCP

Model Context Protocol server for OPNsense firewall management. Designed for use with Hermes Agent and any MCP-compatible client.

Features

• 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