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

• A Firewalla box managed by Firewalla MSP (the MSP API requires an active MSP subscription), and an MSP API personal access token (MSP dashboard → Settings → API)

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

Related MCP server: Firewalla MCP Server

Configuration

The server reads its configuration from environment variables at startup:

Resolve the token from a secrets manager rather than storing it in plaintext:

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

No clone needed — run straight from GitHub with uvx:

claude mcp add firewalla \
  --env FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net" \
  --env FIREWALLA_TOKEN="$(op read 'op://Vault/Firewalla PAT/password')" \
  -- uvx --from git+https://github.com/djuntgen/firewalla-mcp firewalla-mcp

Or from a local clone:

git clone https://github.com/djuntgen/firewalla-mcp.git && cd firewalla-mcp && uv sync
claude mcp add firewalla \
  --env FIREWALLA_MSP_DOMAIN="your-alias.firewalla.net" \
  --env FIREWALLA_TOKEN="$(op read 'op://Vault/Firewalla PAT/password')" \
  -- 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).

Note on token storage: --env values are stored in plaintext in your MCP client's config file (e.g. ~/.claude.json). To keep the token out of persistent config entirely, register a small wrapper script as the command instead — it exports the variables (resolving the token live from your secrets manager) and execs uvx --from git+https://github.com/djuntgen/firewalla-mcp firewalla-mcp. See SECURITY.md.

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).

update_rule note: Firewalla's MSP API has no rule-edit endpoint, so update_rule recreates the rule (create replacement → delete original). The rule id changes, and the returned value reports both the deleted id and the new rule.

Error handling

• HTTP 4xx responses fail immediately (no retry), raising FirewallaAPIError(status_code, body); error bodies are truncated to keep failures readable.

• HTTP 429 (rate limited) is retried once, honoring Retry-After up to 10s.

• HTTP 5xx and connection errors are retried once (0.5s backoff) — except for the non-idempotent creates (create_rule, create_target_list), which are never retried, so a timed-out create can't silently duplicate a firewall rule.

• Non-JSON responses (e.g. an HTML error page from a proxy) raise a readable error instead of a decoder traceback.

Development

uv sync
uv run pytest -v
uv run ruff check . && uv run ruff format --check .

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

License

MIT