Firewalla MCP Server

A read-only Model Context Protocol (MCP) server that connects to your Firewalla Gold via its local API — no MSP subscription required.

Built for AI-powered network security monitoring. Connect it to Claude Code, Claude Desktop, or any MCP-compatible client and query your firewall's alarms, devices, traffic flows, and network stats using natural language.

Features

• Read-only by design — cannot modify rules, dismiss alarms, or change any settings
• 100% local — talks directly to your Firewalla box on your LAN (port 8833), no cloud dependency
• Free — uses the local API, no MSP subscription needed
• MCP standard — works with any MCP client (Claude Code, Claude Desktop, etc.)

Tools

Devices & Traffic

Security & Rules

Network & System

Prerequisites

• Firewalla Gold (other models may work but are untested)
• Node.js 18+
• Your Mac/PC must be on the same network as the Firewalla
• An ETP keypair (generated during one-time pairing — see below)

Installation

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

Pairing (One-Time Setup)

Before the MCP server can talk to your Firewalla, you need to generate an authentication keypair (ETP token). This is the same pairing mechanism the Firewalla mobile app uses — think of it as registering a new "device" with your Firewalla box.

This step uses a separate utility called firewalla-tools. It is not a dependency of this project — you only need it once to generate your .pem key files. After pairing is complete, you can delete it.

1. Clone firewalla-tools (temporary)

git clone https://github.com/lesleyxyz/firewalla-tools.git
cd firewalla-tools
npm install

2. Enable Additional Pairing

In the Firewalla app on your phone:

1. Tap your Firewalla box
2. Go to Settings → Advanced → Allow Additional Pairing
3. Toggle it ON — a QR code will appear on screen

3. Get the QR Code JSON

The pairing tool needs the JSON data encoded in the QR code. To get it:

1. Screenshot the QR code shown in the Firewalla app
2. Scan the screenshot with a QR code reader app (or use your phone's built-in camera)
3. The QR code decodes to a JSON string that looks like:

   {"gid":"...","seed":"...","license":"...","ek":"...","ipaddress":"..."}

1. Copy that JSON string — you'll paste it in the next step

4. Generate the Keypair

From the firewalla-tools directory:

cd create-etp-token
node index.js

The tool will prompt you for:

1. Email — just a label (e.g., [email protected]), used for display in the Firewalla app
2. QR code JSON — paste the JSON string from step 3
3. Firewalla IP — your box's IP address (e.g., 10.0.1.1 — this is usually your default gateway)
4. Create new keypair? — choose Yes

This generates etp.public.pem and etp.private.pem in the current directory.

Tip: To find your Firewalla's IP, run netstat -rn | grep default — the gateway IP is your Firewalla.

5. Store the Keys

Move the .pem files somewhere secure:

mkdir -p ~/.firewalla
mv etp.public.pem etp.private.pem ~/.firewalla/
chmod 600 ~/.firewalla/*.pem

Keep these files safe — they are your authentication credentials.

6. Clean Up

You no longer need firewalla-tools — feel free to delete it:

cd ../..
rm -rf firewalla-tools

Usage

With Claude Code

Add the server to your global config (~/.claude.json) under mcpServers:

{
  "mcpServers": {
    "firewalla": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/firewalla-mcp/dist/index.js"],
      "env": {
        "FIREWALLA_IP": "10.0.1.1",
        "FIREWALLA_PUBLIC_KEY_PATH": "/Users/yourname/.firewalla/etp.public.pem",
        "FIREWALLA_PRIVATE_KEY_PATH": "/Users/yourname/.firewalla/etp.private.pem"
      }
    }
  }
}

Then restart Claude Code. The Firewalla tools will be available in all sessions.

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "firewalla": {
      "command": "node",
      "args": ["/path/to/firewalla-mcp/dist/index.js"],
      "env": {
        "FIREWALLA_IP": "10.0.1.1",
        "FIREWALLA_PUBLIC_KEY_PATH": "/Users/yourname/.firewalla/etp.public.pem",
        "FIREWALLA_PRIVATE_KEY_PATH": "/Users/yourname/.firewalla/etp.private.pem"
      }
    }
  }
}

With MCP Inspector (debugging)

FIREWALLA_IP=10.0.1.1 \
FIREWALLA_PUBLIC_KEY_PATH=~/.firewalla/etp.public.pem \
FIREWALLA_PRIVATE_KEY_PATH=~/.firewalla/etp.private.pem \
npx @modelcontextprotocol/inspector node dist/index.js

Environment Variables

Example Queries

Once connected to an MCP client, try:

• "Show me all active security alarms"
• "List every device on my network"
• "Who are the top bandwidth consumers?"
• "Show me devices grouped by VLAN"
• "Which devices went offline in the last 12 hours?"
• "Show me network flows for device AA:BB:CC:DD:EE:FF"
• "Search for all connections to netflix.com in the last 24 hours"
• "What DNS queries did my smart TV make today?"
• "What traffic has been blocked by the firewall today?"
• "Show me all my firewall rules"
• "What block/allow target lists do I have?"
• "What Firewalla features are enabled?"
• "Is my Firewalla box healthy?"
• "What firmware version is running?"
• "How's my WAN latency and packet loss?"
• "Show me per-WAN bandwidth usage"
• "What's the status of my VPN connections?"
• "Show me my network segments and VLANs"

Project Structure

firewalla-mcp/
├── src/
│   ├── index.ts              # MCP server entry (stdio transport)
│   ├── firewalla-client.ts   # Firewalla local API wrapper
│   └── tools/
│       ├── alarms.ts         # get_alarms
│       ├── devices.ts        # get_devices, get_top_talkers, get_clients_by_network, get_offline_devices
│       ├── dns.ts            # get_dns_queries
│       ├── flows.ts          # get_device_flows, search_flows, get_audit_logs
│       ├── network.ts        # get_network_status, get_network_stats, get_network_performance, get_wan_usage
│       ├── rules.ts          # get_rules, get_features, get_target_lists
│       ├── system.ts         # get_system_info
│       ├── vlans.ts          # get_vlans
│       └── vpn.ts            # get_vpn_status
├── dist/                     # Compiled JS (after build)
├── package.json
├── tsconfig.json
└── CLAUDE.md                 # AI agent project spec

Security

• Read-only only — this server cannot modify your Firewalla configuration
• Local network only — communicates directly with your Firewalla box, no cloud relay
• Key-based auth — uses the same ETP token mechanism as the Firewalla mobile app
• Sensitive data redacted — WiFi passwords, WireGuard private keys, tokens, credentials, API keys, passphrases, and pre-shared keys are automatically stripped from output
• Input limits — all count parameters are clamped to a max of 5000 to prevent excessive data retrieval
• Keep your `.pem` files secure — they grant read access to your network data

Credits

• node-firewalla — Firewalla local API client library
• firewalla-tools — One-time pairing utility for generating ETP auth keys (not a runtime dependency)
• MCP TypeScript SDK — Model Context Protocol server framework

License

MIT — see LICENSE