coreyhines/opnsense-mcp

MCP server for OPNsense firewall operations (ARP, DHCP, logs, rules, interfaces, system status, packet capture).
Use one of two deployment modes:
- STDIO (local): best for Cursor/Claude Code/Continue running the server process directly.
- SSE (centralized): best for shared, long-lived service over HTTPS.
Demo
Query your firewall with Claude Code CLI. Live example with real network data:
Why This Exists
Built this because SSH'ing into the firewall to check logs or grab ARP data got old fast. Now you can ask Claude:
- "What's happening on the network right now?"
- "Show me the latest firewall blocks"
- "Tell me about that host"
- "Capture packets from the suspicious traffic"
Claude handles the firewall query via MCP and gives you analysis + context in one shot. Works on homelab or business deployments equally well.
Quick Start
1) Local setup (required for both modes)
Edit ~/.env:
2) Choose mode
Mode A: STDIO (local IDE/client)
Configure your MCP client to launch mcp_start.sh:
See full guide: docs/GETTING_STARTED.md.
Mode B: SSE (centralized service)
Run the Linux installer (Podman + quadlet + Caddy TLS):
Clients connect to:
See deployment docs:
- docs/CENTRALIZED_DEPLOY_SPEC.md
- deploy/README.md
- deploy/TLS.md
What Is Available
Primary tools:
- Discovery: arp, dhcp, lldp
- Monitoring: system, get_logs, packet_capture
- Firewall rules: fw_rules, mkfw_rule, set_fw_rule, toggle_fw_rule, rmfw_rule
- Interfaces: interface_list
Full reference: docs/REFERENCE/FUNCTION_REFERENCE.md
What's New (June 2026)
Five PRs landed recently. See docs/FEATURES_UPDATE.md for full details and usage examples.
- **Streamable HTTP transport** — native FastMCP server supports stdio, sse, and streamable-http (MCP spec 2025-03-26). Deployed via deploy/install.sh.
- **DHCP client_id (DUID) support** — mk_dhcp_host and move_dhcp_host accept an optional DUID for stateful DHCPv6 matching.
- **Semver image tags** — images are tagged from pyproject.toml version + git short SHA (1.0.0-dev.a1b2c3d) or release tags (1.0.0).
- **Container registry** — pinned tags only; :latest is rejected. Set OPNSENSE_MCP_IMAGE_REPO, or build locally with --build-local.
- **install.sh readonly fix** — Bash readonly clash between install.sh and lib.sh resolved.
Use Cases
- **Homelab network troubleshooting** — Query firewall logs from terminal, get Claude's take on what's happening
- **Security operations** — Automate incident triage: "Analyze the last hour of blocks"
- **Infrastructure automation** — Write MCP-aware scripts that query firewall state dynamically
- **DevOps troubleshooting** — Quick VLAN/interface status checks without SSH sessions
Feedback
First 10 users get feedback incorporated into the tool. If you find bugs or have ideas, file an issue or discussion.