mcp-opnsense

MCP server for OPNsense firewall management. Exposes 299 tools covering system status & diagnostics, services, cron, interfaces/VLANs, DHCP, Unbound DNS, firewall rules & aliases, NAT, traffic shaping, OpenVPN, WireGuard, IPsec, HAProxy, IDS/IPS, certificates, users, captive portal, and more — all via the OPNsense REST API.

Quick Start

With uvx (recommended):

OPNSENSE_HOST=https://192.168.1.1 \
OPNSENSE_API_KEY=yourkey \
OPNSENSE_API_SECRET=yoursecret \
uvx mcp-opnsense

With Docker:

docker run -i \
  -e OPNSENSE_HOST=https://192.168.1.1 \
  -e OPNSENSE_API_KEY=yourkey \
  -e OPNSENSE_API_SECRET=yoursecret \
  ghcr.io/aaronckj/mcp-opnsense:latest

Add to Claude Code:

claude mcp add opnsense -- uvx mcp-opnsense

Or with environment configured inline:

claude mcp add opnsense -s user \
  -e OPNSENSE_HOST=https://192.168.1.1 \
  -e OPNSENSE_API_KEY=yourkey \
  -e OPNSENSE_API_SECRET=yoursecret \
  -- uvx mcp-opnsense

mcp.json snippet (Claude Desktop, Cursor, or any MCP client):

{
  "mcpServers": {
    "opnsense": {
      "command": "uvx",
      "args": ["mcp-opnsense"],
      "env": {
        "OPNSENSE_HOST": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "yourkey",
        "OPNSENSE_API_SECRET": "yoursecret"
      }
    }
  }
}

Creating API Credentials

In OPNsense: System → User Manager → Users → edit a user → API keys → Add key. Copy the key and secret (the secret is only shown once).

Configuration

Tools

This server exposes 299 tools. Most domains follow a consistent CRUD pattern: list_*, get_*, add_*, update_*, delete_*, and toggle_*. Tools are grouped by domain below (counts sum to 299):

The examples column is illustrative, not exhaustive. Run the server and ask your MCP client to list tools for the full inventory.

⚠️ Destructive / high-impact tools

Many tools mutate live firewall configuration and apply immediately. Treat the following as destructive and confirm before invoking — several can drop your connection or take the firewall offline:

• Whole-system: reboot_system, shutdown_system, perform_firmware_upgrade, install_plugin, remove_plugin
• Config deletion (37 delete_* tools): e.g. delete_firewall_rule, delete_port_forward, delete_user, delete_vlan, delete_certificate, delete_ipsec_tunnel, delete_unbound_host
• Service / state control: restart_service, stop_service, start_service, restart_unbound, restart_haproxy, hard_restart_haproxy, restart_ids, stop_ids, start_ids
• Flush / disconnect: flush_states, flush_firewall_states, flush_arp_table, flush_dns_cache, flush_alias, flush_ids_alerts, disconnect_openvpn_session, disconnect_captive_portal_client
• Apply: apply_changes commits staged firewall/NAT changes

Scope the API credentials to the least privilege your use case needs, and consider a read-only OPNsense user if you only want status/inspection tools.

Development

git clone https://github.com/aaronckj/mcp-opnsense
cd mcp-opnsense
uv sync --extra dev
uv run pytest -v