firewalla-mcp

A local MCP server exposing the Firewalla MSP API — boxes, alarms, rules, devices, flows, target lists, and trends — as tools for Claude Code and other MCP-compatible clients.

Full read/write: list and inspect your Firewalla boxes, alarms, devices, and flows, and create/pause/resume/delete firewall rules and target lists, all from natural-language requests to your AI assistant.

Prerequisites

• An MSP-managed Firewalla box, and an MSP API personal access token (Firewalla MSP dashboard → Settings → API)

• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)

Related MCP server: Firewalla MCP Server

Setup

git clone https://github.com/djuntgen/firewalla-mcp.git
cd firewalla-mcp
uv sync

The server reads two environment variables at startup:

Export them however fits your workflow — a .env file loaded by your shell, a secrets manager, or directly:

export FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net"
export FIREWALLA_TOKEN="$(op read 'op://Vault/Firewalla PAT/password')"  # example using 1Password CLI

Register with Claude Code

claude mcp add firewalla --env FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net" --env FIREWALLA_TOKEN="your-token" -- uv run --project /path/to/firewalla-mcp firewalla-mcp

This registers the server at local scope (machine-specific, not committed to a shared .mcp.json).

Tools

One tool per Firewalla MSP API v2 operation:

Full read/write — there is no server-side dry-run gate on writes. Rely on your MCP client's normal confirmation prompts before destructive actions (delete_rule, delete_target_list, delete_alarm).

Error handling

HTTP 4xx responses fail immediately. HTTP 5xx responses and connection errors are retried once (0.5s backoff) before failing, raising FirewallaAPIError(status_code, body).

Development

uv sync
uv run pytest -v

Tests are fully mocked (respx) — no real Firewalla API calls or credentials are needed to run the suite. See CONTRIBUTING.md.

License

MIT