mcp-opnsense

MCP server for managing OPNsense firewalls via Claude Code. Read-only tools first — write support planned.

Setup

1. Install dependencies

npm install
npm run build

2. Create OPNsense API user

⚠️ Do not use the admin/root user. Create a dedicated user with minimal privileges.

2a. Create a group

1. System → Access → Groups → Add

   • Group name: mcp_readonly
   • Assign these privileges:

   Privilege	Needed for
   GUI - Firewall: Rules	list-firewall-rules, get-firewall-rule, list-aliases, get-alias
   GUI - Gateways	get-gateway-status
   GUI - Diagnostics: Interface	get-interface-stats

2. Save

2b. Create a user

1. System → Access → Users → Add

   • Username: mcp
   • Password: (generate a strong random password)
   • Group: mcp_readonly

2. Save

2c. Generate API key

1. System → Access → API Keys → Add
   • User: mcp
   • Download the key file (INI/txt format)
   • Keep it secure — it contains the key and secret

Note: OPNsense ACLs are page-level — the "Firewall: Rules" privilege grants both read and write API access. The MCP server currently only exposes read tools, so this is safe. When write tools are added, the same user will work without changes.

3. Create config file

mkdir -p ~/.mcp-opnsense
cp config.example.json ~/.mcp-opnsense/config.json
chmod 600 ~/.mcp-opnsense/config.json

Edit ~/.mcp-opnsense/config.json with your OPNsense connection details:

{
  "instances": [
    {
      "name": "home",
      "url": "https://192.168.1.1",
      "api_key": "your-key-here",
      "api_secret": "your-secret-here",
      "allow_insecure": true
    },
    {
      "name": "office",
      "url": "https://10.0.0.1",
      "api_key": "your-key-here",
      "api_secret": "your-secret-here",
      "allow_insecure": false
    }
  ],
  "default": "home"
}

• name — short label for this instance
• url — OPNsense base URL (HTTPS without trailing /api)
• api_key / api_secret — from the downloaded key file in step 2c
• allow_insecure — set true if using self-signed certificates (common on LAN)

Set OPNSENSE_CONFIG_PATH env var to override the config file location.

4. Configure Claude Code

Add to your Claude Code MCP config (usually ~/.claude/settings.json):

{
  "mcpServers": {
    "opnsense": {
      "command": "node",
      "args": ["/path/to/mcp-opnsense/dist/index.js"],
      "env": {}
    }
  }
}

Or use the dev mode (no build step):

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-opnsense/src/index.ts"],
      "env": {}
    }
  }
}

Available Tools

All tools accept an optional instance parameter to target a specific OPNsense instance (uses the configured default if omitted).

Tool	Description
list-firewall-rules	List firewall filter rules with optional search
get-firewall-rule	Get a single rule by UUID
list-aliases	List firewall aliases (host, network, port, URL types)
get-alias	Get a single alias by UUID
get-interface-stats	Get network interface statistics
get-gateway-status	Live gateway monitoring (online/offline, latency, loss)

Note: The OPNsense API only manages rules created under Firewall → Automation → Filter. Legacy rules from Firewall → Rules are not accessible via API.

Development

# Run typecheck
npm run typecheck

# Run dev server (via tsx, no build step)
npm run dev

# Build to dist/
npm run build

# Run production
npm start

Multi-Instance

Define all your OPNsense endpoints in ~/.mcp-opnsense/config.json under the instances array. Use the instance parameter in any tool to target a specific instance:

"Check the gateway status for the office firewall"
→ get-gateway-status(instance: "office")

When no instance is specified, the default from config is used.

Known Limitations

• Automation rules only — the API only exposes rules from Firewall → Automation. Classic Firewall → Rules entries are not reachable.
• Self-signed certs — set allow_insecure: true for LAN OPNsense boxes with self-signed TLS.
• API permissions — the OPNsense user must have the relevant permissions (Gateways, Firewall, Diagnostics) assigned.

Roadmap

• [x] Read-only tools (firewall rules, aliases, diagnostics)
• [ ] Write tools — add/update aliases (low risk)
• [ ] Write tools — toggle firewall rules (with rollback)
• [ ] Write tools — create/update/delete firewall rules
• [ ] DHCP leases & static mappings
• [ ] DNS overrides (Unbound/Dnsmasq)
• [ ] VPN status (WireGuard, OpenVPN)
• [ ] Service management (restart, status)
• [ ] Config backup & restore via API

License

MIT