Firewalla MCP Server

# MCP Servers [](https://github.com/drewrad8/mcps/actions/workflows/ci.yml) [](https://codecov.io/gh/drewrad8/mcps) A collection of Model Context Protocol (MCP) servers for network security and monitoring. ## Servers ### Firewalla MCP Server A comprehensive MCP server for interacting with [Firewalla](https://firewalla.com) network security devices. Provides network monitoring, device management, and security rule configuration through MCP tools. #### Features - **Network Monitoring**: Query network flows, analyze traffic patterns, detect security events - **Device Management**: List, search, and get details for all network devices - **Security Rules**: Allow/block/deny categories, apps, or specific targets per device - **Traffic Analysis**: Top talkers, blocked traffic, protocol distribution, country stats - **Trend Data**: 24h/7d/30d traffic trends with peak detection #### Installation ```bash cd firewalla npm install npm run build ``` #### Configuration **Option 1: Environment Variables (Recommended)** ```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" # debug, info, warn, error ``` **Option 2: Runtime Configuration** Use the `configure_firewalla` MCP tool after connecting. #### Usage ```bash # Start the server npm run start # Development mode (build + run) npm run dev ``` #### Available MCP Tools | Tool | Description | |------|-------------| | `configure_firewalla` | Set API credentials (or use env vars) | | `get_config_status` | Check configuration status and source | | `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 | ## Development ### Commands ```bash npm run build # Compile TypeScript npm run start # Run the server npm run dev # Build and run npm test # Run tests npm run test:watch # Run tests in watch mode npm run test:coverage # Run tests with coverage ``` ### Testing The project uses [Vitest](https://vitest.dev/) for testing with 32 tests covering: - API client functionality - Error recovery and retry logic - Environment variable configuration - Structured logging - Custom error classes ### Architecture ``` firewalla/ ├── server.ts # Main server implementation ├── server.test.ts # Test suite ├── vitest.config.ts # Test configuration ├── package.json # Dependencies └── api_samples/ # Reference API responses ``` ### Key Components - **Logger**: Structured JSON logging to stderr with configurable levels - **FirewallaAPI**: HTTP client with retry logic and exponential backoff - **FirewallaMCPServer**: MCP server with 13 tools for Firewalla interaction - **Error Classes**: `FirewallaAPIError`, `FirewallaAuthError`, `FirewallaNetworkError`, `FirewallaRateLimitError` ### Error Recovery The API client 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) - Configurable retry settings ### Logging Structured JSON logs to stderr (stdout reserved for MCP): ```json {"service":"firewalla-mcp","timestamp":"...","level":"info","message":"Server started","context":{"transport":"stdio"}} ``` ## License MIT