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.- Streamable HTTP (centralized): best for a shared, long-lived service over HTTPS, at
/mcp.
Query your firewall with Claude Code CLI. Live example with real network data:
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.
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
cp examples/.env.example ~/.envEdit ~/.env:
OPNSENSE_API_KEY=your_api_key
OPNSENSE_API_SECRET=your_api_secret
OPNSENSE_FIREWALL_HOST=your.firewall.host
# HTTP transports only; stdio ignores it. Generate with: openssl rand -hex 32
MCP_SECRET_KEY=Configure your MCP client to launch mcp_start.sh:
{
"mcpServers": {
"opnsense-mcp": {
"command": "/bin/bash",
"args": ["/absolute/path/to/opnsense-mcp/mcp_start.sh"],
"cwd": "/absolute/path/to/opnsense-mcp"
}
}
}See full guide: docs/GETTING_STARTED.md.
Run the Linux installer (Podman + quadlet + Caddy TLS):
sudo bash deploy/install.shClients connect to:
https://<your-hostname>/mcp
The deployed container serves streamable HTTP only. There is no /sse
endpoint and no /health route; both answer 404.
Every request must send Authorization: Bearer <MCP_SECRET_KEY>. The server
refuses to start on an HTTP transport when the key is blank or a placeholder.
See deployment docs:
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
Five PRs landed recently. See docs/FEATURES_UPDATE.md for full details and usage examples.
- Streamable HTTP transport — native FastMCP server supports
stdioandstreamable-http(MCP spec 2025-03-26).deploy/install.shdeploys streamable HTTP at/mcp. - DHCP client_id (DUID) support —
mk_dhcp_hostandmove_dhcp_hostaccept an optional DUID for stateful DHCPv6 matching. - Semver image tags — main builds are tagged as a prerelease of the next patch after the
pyproject.tomlversion (1.0.1-dev.a1b2c3dafter 1.0.0) or release tags (1.0.0). - Container registry — pinned tags only;
:latestis rejected. SetOPNSENSE_MCP_IMAGE_REPO, or build locally with--build-local. - install.sh readonly fix — Bash
readonlyclash betweeninstall.shandlib.shresolved.
- 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
First 10 users get feedback incorporated into the tool. If you find bugs or have ideas, file an issue or discussion.
scripts/risk_map.py ranks source files by defect likelihood from git history —
churn times fix density — so a review reads the risky files first and can stop
early. It finds no bugs; it finds where they concentrate.
python3 scripts/risk_map.py --top 15
CI runs it on every pull request alongside a complexity report (radon) and a
security-pattern pass (bandit) in the advisory Insights workflow, which
never blocks a merge. Thresholds that gate the build come later, once the
numbers are trusted.
- Start here:
docs/GETTING_STARTED.md - Claude Code specifics:
docs/CLAUDE_CODE_INTEGRATION.md - Centralized deploy spec:
docs/CENTRALIZED_DEPLOY_SPEC.md - Contributor guide:
docs/DEVELOPMENT/CONTRIBUTING.md - Brand assets:
docs/assets/
This project is released under the MIT License.

