firewalla-mcp-server

A read-only Model Context Protocol (MCP) server that lets Claude audit your Firewalla configuration and network security posture via the Firewalla MSP API.

Read-only by design. This server cannot block/unblock devices, create or modify rules, pause services, or make any changes to your Firewalla. It only observes.

What it does

Exposes 8 tools that Claude can use to inspect your Firewalla — devices on your network, active rules, security alarms, network flows, and block/allow target lists.

Example prompts

Security audits

These prompts treat Claude as a network security professional conducting a structured review of your Firewalla configuration. They work best in Claude Desktop or Claude Code where the Firewalla MCP tools are available.

Full network security audit:

You are a senior network security engineer conducting a comprehensive audit of my home network. Using the Firewalla MCP tools, perform the following review and present your findings in a structured report with severity ratings (Critical / High / Medium / Low / Informational):

1. Device inventory — Pull the complete device list. Flag any devices with unrecognized MAC vendors, devices not being monitored, or unexpected router-class devices that could indicate a rogue access point.
2. Rule audit — Review all block/allow rules. Identify any allow rules that are overly permissive (broad scope, inbound direction, no device restriction). Flag rules with zero hit counts that may be stale.
3. Alarm review — Search recent alarms grouped by type and severity. Identify any patterns (repeated alarms from the same device, alarms from unexpected countries, alarms targeting devices that shouldn't have external exposure).
4. Target list coverage — Review which block lists are active. Assess whether the current list configuration provides adequate coverage against common threat categories (malware, C2, phishing, cryptomining, newly registered domains).

Conclude with a prioritized list of recommended actions I should take to improve my network security posture.

Firewall rule gap analysis:

Act as a firewall policy analyst. Pull all of my Firewalla rules and the complete device list, then cross-reference them. I need you to identify: (1) devices that have no rules scoped to them at all — are they relying entirely on global rules, and is that intentional? (2) allow rules that grant inbound access — what devices do they target and is the scope appropriately narrow? (3) block rules that have never fired (hit count = 0) — are they stale or is the threat they guard against simply not present? Present your findings as a table for each category with your assessment and recommended action.

Suspicious traffic investigation:

I want to investigate whether any devices on my network are communicating with unexpected external destinations. Search my recent network flows for any traffic to regions outside the US that was NOT blocked by Firewalla. Group the results by device and destination country. For any device that shows unblocked traffic to unusual regions, cross-reference it against my device list to identify what the device is, then check if there are any alarms associated with it. Summarize your findings with a risk assessment for each flagged device.

Quick queries

These are shorter prompts for everyday monitoring and spot checks:

• "List all devices on my network and flag any that have an unknown MAC vendor or aren't being monitored by Firewalla."
• "Show me all allow rules on my Firewalla. Are any of them scoped too broadly?"
• "What are the top alarm types firing on my network right now? Group them by type and give me a count."
• "Check which Firewalla block lists I have active and how many entries each one has. Am I missing any important categories?"
• "Search for any blocked flows in the last 24 hours and group them by destination country. Which countries are showing up the most?"
• "Pull my Firewalla box info — is it online, what firmware version is it running, and how many active alarms are there right now?"

Tools

Tool	Description
firewalla_list_boxes	Discover Firewalla boxes on the MSP account (model, firmware, online status, device/rule/alarm counts)
firewalla_list_devices	Inventory all devices on the network (IP, MAC vendor, device type, online status, monitoring flag)
firewalla_search_flows	Search network flows with query filters, grouping, and cursor pagination
firewalla_search_alarms	Search active security alarms with query filters, grouping, and cursor pagination
firewalla_get_alarm	Fetch full detail for a single alarm by box + alarm ID
firewalla_list_rules	Audit configured block/allow rules (action, direction, target, scope, hit count)
firewalla_list_target_lists	List block/allow target lists (Firewalla-managed and user-defined)
firewalla_get_target_list	Fetch metadata for a single target list by ID

All tools support response_format: "json" | "markdown" and are annotated readOnlyHint: true.

Prerequisites

1. A Firewalla box linked to an MSP account. Even standalone (non-fleet) boxes use the MSP API — it's the only supported public API.

2. An MSP personal access token. Generate one at:

   • Log in to your MSP portal at https://<your-subdomain>.firewalla.net
   • Go to Account Settings → Personal Access Tokens
   • Create a new token and save it somewhere secure

   For detailed setup instructions, see Getting Started with the Firewalla MSP API.

3. Node.js 18+

Install

git clone https://github.com/productengineered/firewalla-mcp.git
cd firewalla-mcp
npm install
npm run build

Configuration

The server reads two environment variables:

Variable	Description	Example
FIREWALLA_MSP_DOMAIN	Your MSP subdomain (no https://, no trailing slash)	yourname.firewalla.net
FIREWALLA_MSP_TOKEN	Personal access token from MSP Account Settings	fwtoken_abc123...

For local development, copy .env.example to .env and fill in your values:

cp .env.example .env
# edit .env with your real values

Usage with Claude Desktop

Add to your claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "firewalla": {
      "command": "node",
      "args": ["/absolute/path/to/firewalla-mcp/dist/index.js"],
      "env": {
        "FIREWALLA_MSP_DOMAIN": "yourname.firewalla.net",
        "FIREWALLA_MSP_TOKEN": "your-token-here"
      }
    }
  }
}

Note: Claude Desktop launches with a minimal PATH. If node isn't found, use the absolute path to your Node.js binary (e.g. the output of which node).

Restart Claude Desktop after editing the config.

Usage with Claude Code

claude mcp add-json --scope user firewalla '{
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/firewalla-mcp/dist/index.js"],
  "env": {
    "FIREWALLA_MSP_DOMAIN": "yourname.firewalla.net",
    "FIREWALLA_MSP_TOKEN": "your-token-here"
  }
}'

Verify with:

claude mcp list
# firewalla: ... - ✓ Connected

New Claude Code sessions will have firewalla_* tools available automatically.

Development

# Source env for local dev
set -a; source .env; set +a

# Run with auto-reload
npm run dev

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

Firewalla API documentation

• Firewalla MSP API reference
• MSP API examples (GitHub)
• Getting started with the MSP API

License

MIT