firewalla-mcp-server

Discover the Firewalla boxes linked to this MSP account. This is the entry point for every audit — the returned gid is required by other tools.

Use this to answer:

• "Is my box online and reporting in?"

• "What firmware version is it running?"

• "How many active devices, rules, alarms are there right now?"

Args:

• group (string, optional): Filter to a specific group id.

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { count: number, boxes: Array<{ gid: string, // box id — save this, other tools need it name: string, model: string, // e.g. "gold_plus" mode: string, // routing mode version: string, // firmware online: boolean, publicIP?: string, lastSeen?: number, // epoch seconds — not always populated license?: string, location?: string, deviceCount: number, ruleCount: number, alarmCount: number, // currently-active alarms group?: { id, name } }> }

Audit framing:

• Offline box → can't observe current state; surface it.

• High alarmCount → follow up with firewalla_search_alarms.

• publicIP exposed unexpectedly → investigate with firewalla_search_flows.

Inventory every device Firewalla tracks — the "who's on my network right now" primitive.

Use this to answer:

• "Are there any unknown/rogue devices on my network?"

• "Which devices aren't being monitored?"

• "What's the MAC vendor breakdown across my network?"

• "Any router-class devices I didn't expect?"

Args:

• box (string, optional): Filter to devices on a specific box gid.

• online_only (boolean, optional): Drop offline devices client-side.

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { count: number, // devices after client-side filtering total: number, // devices returned by the API (pre-filter) devices: Array<{ id: string, // typically MAC gid: string, // box the device is attached to name: string, ip: string, mac?: string, macVendor?: string, ipReserved?: boolean, online: boolean, network?: { id, name }, deviceType?: string, // e.g. "phone", "computer", "iot" isRouter?: boolean, isFirewalla?: boolean, monitoring?: boolean, // false = device excluded from monitoring totalDownload?: number, // bytes (lifetime) totalUpload?: number }> }

Audit framing:

• Unknown macVendor → possible squatter or spoofed MAC.

• monitoring=false → device is excluded from Firewalla's visibility; review whether that's intentional.

• Unexpected isRouter=true → shadow router on the LAN.

• ipReserved=false on a server that should have a static lease → risk of address drift.

Search network flows observed by Firewalla with the MSP query grammar. Use this to inspect what's actually happening on the wire.

Use this to answer:

• "Any outbound flows to region:CN that were NOT blocked?"

• "Top talkers by download volume over the last 24h?"

• "Which devices have made the most connections to blocklisted categories?"

• "Are there any inbound flows from the public internet that shouldn't exist?"

• "Flows from device X in the last hour?"

Args:

• query (string, optional): Firewalla query grammar. Examples: blocked:true, region:CN, direction:inbound, device.mac:AA:BB:CC:DD:EE:FF, category:malware, ts:>1700000000, combined with AND/OR.

• group_by (string, optional): e.g. device, device,destination, region.

• sort_by (string, optional): e.g. ts:desc (default), download:desc.

• limit (number, 1–500, default 200).

• cursor (string, optional): pagination cursor from a prior response.

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { count: number, // items in this page next_cursor?: string, flows: Array<{ ts, gid, protocol, direction, block?, blockType?, download?, upload?, total?, duration?, count?, device?: { id, ip?, name?, network? }, source?: { id?, ip?, name?, port? }, destination?: { id?, ip?, name?, port? }, // Flow-level classification fields (NOT nested under destination): country?, region?, domain?, category? }> }

Audit framing:

• Start broad with sort_by=download:desc to find top bandwidth users.

• Narrow with query when you've found a device/region of interest.

• block=false flows to a category:malware destination = missed block, investigate rules.

• Use group_by for aggregates; use limit=50 or so for fine-grained review.

Search active Firewalla alarms with the MSP query grammar. This is the primary tool for "what security events are happening right now?" audits.

Use this to answer:

• "Any alarms from devices not in a known group?"

• "How many alarms of type X in the last 24h, grouped by device?"

• "Which remote countries are triggering the most alarms?"

• "Any alarms relating to a specific device (by MAC)?"

Args:

• query (string, optional): Firewalla query grammar. Examples: type:1, device.mac:AA:BB:CC:DD:EE:FF, remote.country:CN, ts:>1700000000.

• group_by (string, optional): e.g. device, type, remote.country.

• sort_by (string, optional): e.g. ts:desc (default), ts:asc.

• limit (number, 1–500, default 200).

• cursor (string, optional): pagination cursor from a prior response.

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { count: number, // items in this page next_cursor?: string, // echo back to fetch the next page alarms: Array<{ aid, gid, type, ts, message, status?, device?: { id?, name?, ip? }, remote?: { ip?, country?, name?, region?, category? } }> }

Audit framing:

• Alarm from an unknown MAC (device.id not in firewalla_list_devices) → rogue device.

• Repeated alarms to the same remote.country → likely a single piece of malware, check firewalla_list_rules.

• When counts get big, use group_by=type first for a birds-eye view, then drill.

Fetch the full detail of a single alarm by gid (box id) + aid (alarm id). Use this after firewalla_search_alarms to drill into one event.

Args:

• gid (string, required): Box id (from firewalla_list_boxes).

• aid (string, required): Alarm id (from firewalla_search_alarms).

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns the full alarm record, which may include device, remote endpoint, category, timestamps, and any alarm-type-specific detail fields the MSP API surfaces.

Audit configured block / allow rules. Read-only — this tool does NOT pause, resume, create, or modify rules.

Use this to answer:

• "Do I have any allow rules that bypass Firewalla's default blocks?"

• "Which rules haven't fired in 90 days (candidates to remove)?"

• "Are my block rules scoped to the right device/group?"

• "Any rules with action=allow and broad scope?"

Args:

• query (string, optional): Firewalla query-grammar filter (pass-through). Examples: action:allow, status:paused, target.type:domain.

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { count: number, rules: Array<{ id: string, gid: string, action: string, // "block" | "allow" | "time_limit" | … direction?: string, // "outbound" | "inbound" | "bidirection" status?: string, // "active" | "paused" | "disabled" target: { type, value, dnsOnly?, port? }, scope?: { type?, value? }, notes?: string, hit?: { count?, lastHitTs? }, ts?: number, updateTs?: number }> }

Audit framing:

• action=allow with scope=global → overly permissive, investigate.

• status=paused with no notes → someone disabled a rule and didn't document why.

• hit.count=0 & old updateTs → stale rule, candidate for removal.

List the block/allow target lists available on this MSP account — both Firewalla-managed ("global") and user-defined.

Use this to answer:

• "Which block lists is Firewalla enforcing against?"

• "Have I added any custom target lists, and what are their owners?"

• "What categories (ad, tracker, malware, …) are covered?"

This endpoint returns summaries (including target count per list); call firewalla_get_target_list for the actual targets array.

Args:

• owner (string, optional): Filter by owner (e.g. 'global').

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { count: number, // number of target lists targetLists: Array<{ id: string, name: string, owner: string, // "global" | user id type?: string, // e.g. "ad", "tracker", "malware", "custom" source?: string, // upstream feed source (Firewalla-managed lists) count?: number, // number of entries in the list blockMode?: string, // e.g. "dns" | "ip" beta?: boolean, notes?: string, lastUpdated?: number }> }

Audit framing:

• Custom lists (owner != global) without notes → undocumented intent.

• blockMode=dns only, but target includes raw IPs → mismatch, investigate.

• Zero-count list → may be stale / never populated.

Fetch the metadata for a single target list by id.

MSP API limitation: For Firewalla-managed lists (owner="firewalla"), the MSP API does NOT return individual target entries — it returns the summary plus the aggregate count. User-created lists may include a targets array; if so, we surface it.

Use this to answer:

• "What's the block mode / source / type of list X?"

• "When was list X last updated?"

• "How big is list X?" (use the count / targetCount field)

Do NOT use this to answer:

• "Is domain example.com on list X?" — the entries aren't returned.

• "Give me the first N entries of list X." — same reason.

Args:

• id (string, required): Target-list id (from firewalla_list_target_lists).

• response_format ('markdown' | 'json'): Output format (default: markdown).

Returns: { id, name, owner, type?, source?, blockMode?, notes?, lastUpdated?, count?: number, // summary count reported by the API targetCount: number, // same as count, or actual targets.length when present targets?: string[] // only populated for user-created lists (rare) }