firewalla-mcp-server: Skill for Claude Code

Firewalla — reading the data correctly

This skill is for operating the firewalla-mcp-server MCP tools against a Firewalla MSP account. The server is read-only by default (28 tools; 11 write tools only with FIREWALLA_ENABLE_WRITE_TOOLS=true). Getting a correct answer is mostly about reading the data the right way and knowing what the API cannot tell you. The long form, with a worked example and a copy-paste recipe, is in docs/interpreting-results-guide.md.

Setup (generic)

The server authenticates with FIREWALLA_MSP_TOKEN and FIREWALLA_MSP_ID (your MSP domain, e.g. yourdomain.firewalla.net); FIREWALLA_BOX_ID is optional and retrievable with get_boxes. See the project README for .env setup. On a multi-box account, confirm which box you mean with get_boxes rather than assuming a default.

The traps that produce wrong answers

• A blocked-flow COUNT is not a current state. The flow log retains blocks from before a rule change. Before saying "X is blocked", pull search_flows query:"device.ip:<ip>" (results are newest-first in data.flows), then read the newest flow for the same endpoint — the same domain (or destination_ip) AND protocol. Its blocked value is the current state; a later allowed flow to one endpoint says nothing about a block to a different IP or protocol. If both appear for one endpoint, report the newest and that it was mixed.
• Can a port be blocked? Check — don't assume not. Firewalla allows outbound by default and most rules target domain|category|app|ip|targetlist, but the model DOES support ports: target.type:"remotePort", plus target.port (domain/ip/net) and scope.port. So scan get_network_rules for a remotePort target or a port field on target/scope, AND check live flows on that port show blocked:false — don't answer "no port rules" by assumption.
• Allow vs block precedence is subtle — verify, don't theorize. A device-scoped domain allow and a network-wide IP-level block (a dnsOnly:false category rule) can both apply to a connection to a shared CDN IP. Which wins is internal to the box; read fresh flows rather than inferring from the rule list.
• Query grammar: block:true → status:blocked; bytes: → total:; domain: is the ROOT domain (domain:*.x.com matches nothing); limit ≤ 500 on flows and alarms.
• Shapes (MCP tool output): search_flows returns {success, data:{flows: [...]}, meta}; each data.flows[] has blocked (bool), source_ip, destination_ip, domain, protocol, direction, bytes, timestamp — no portInfo. get_flow_data adds block_type, category and raw source/destination; a flow's category is the flow's classification, not the rule's. A rule is {action: block|allow|timelimit, status, direction, target:{type (… remotePort …), value, dnsOnly?, port?}, scope?: {type: device|group|user|network, value, port?}} — scope may be absent (all devices); dnsOnly:false also enforces at the IP layer.