Firewalla MCP Server

# @drewrad8/firewalla-mcp [](https://www.npmjs.com/package/@drewrad8/firewalla-mcp) [](https://github.com/drewrad8/mcps/actions/workflows/ci.yml) A Model Context Protocol (MCP) server for [Firewalla](https://firewalla.com) network security devices. Enables AI assistants to monitor network traffic, manage devices, and configure security rules. ## Features - **Network Monitoring**: Query network flows, analyze traffic patterns - **Device Management**: List, search, and get details for all network devices - **Security Rules**: Allow/block/deny categories, apps, or specific targets - **Traffic Analysis**: Top talkers, blocked traffic, protocol distribution - **Trend Data**: 24h/7d/30d traffic trends with peak detection ## Installation ```bash npm install -g @drewrad8/firewalla-mcp ``` Or use with npx: ```bash npx @drewrad8/firewalla-mcp ``` ## Configuration Set environment variables before running: ```bash export FIREWALLA_URL="https://my.firewalla.com" export FIREWALLA_TOKEN="your-bearer-token" export FIREWALLA_ID="your-firewalla-device-id" export LOG_LEVEL="info" # optional: debug, info, warn, error ``` Or configure at runtime using the `configure_firewalla` MCP tool. ## Usage ### As a CLI ```bash firewalla-mcp ``` ### With Claude Desktop Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`): ```json { "mcpServers": { "firewalla": { "command": "npx", "args": ["@drewrad8/firewalla-mcp"], "env": { "FIREWALLA_URL": "https://my.firewalla.com", "FIREWALLA_TOKEN": "your-token", "FIREWALLA_ID": "your-device-id" } } } } ``` ## Available Tools | Tool | Description | | ------------------------- | ---------------------------------------------------------- | | `configure_firewalla` | Set API credentials (or use env vars) | | `get_config_status` | Check configuration status | | `query_network_flows` | Query network flows with time filters | | `list_devices` | List all network devices | | `get_device_details` | Get device info by MAC address | | `analyze_network_traffic` | Traffic analysis (summary, top talkers, blocked, security) | | `get_device_traffic` | Per-device traffic analysis | | `get_network_overview` | Comprehensive network overview | | `get_cloud_rules` | Active cloud security rules | | `get_traffic_trends` | Traffic trends (24h/7d/30d) | | `get_firewalla_status` | Firewalla device status | | `search_devices` | Search devices by name/IP/MAC | | `update_device_rules` | Modify device security rules | ## Getting Your Firewalla Credentials 1. Log into the Firewalla app or web interface 2. Navigate to Settings > Developer 3. Generate an API token 4. Note your Firewalla device ID ## Error Handling The server includes robust error handling: - Automatic retry on 5xx errors and network failures - Exponential backoff with jitter - Rate limit handling with Retry-After support - Request timeouts (30s default) ## Logging Structured JSON logs to stderr (stdout reserved for MCP): ```json { "service": "firewalla-mcp", "timestamp": "...", "level": "info", "message": "Server started" } ``` ## Requirements - Node.js >= 18 - Firewalla device with cloud access enabled ## License MIT ## Links - [GitHub Repository](https://github.com/drewrad8/mcps) - [Issue Tracker](https://github.com/drewrad8/mcps/issues) - [Firewalla](https://firewalla.com)