Firewalla

You can run a Firewalla MCP Server to access real-time Firewalla firewall data through a suite of tools. It connects Claude-based clients and other MCP clients to Firewalla via a lightweight MCP bridge, translating client requests into Firewalla API calls and returning results in a consistent, MCP-friendly format.

How to use

Launch the MCP server in either stdio or HTTP transport mode, then connect your MCP client (such as Claude Desktop, Claude Code, or an MCP-enabled editor). Start with a basic health check to confirm the server is up, then issue queries to retrieve alarms, flows, device status, and rule information. Use the HTTP transport when you need external access or multiple clients, and use stdio when you integrate with a local client or a single-process workflow.

How to install

Prerequisites you need before installing are Node.js 18+ and npm, plus a Firewalla MSP account with API access and a online Firewalla device.

# Install the MCP server globally (recommended)
npm install -g firewalla-mcp-server

# Or install locally in your project
npm install firewalla-mcp-server

Configuration and startup

Choose your transport mode and set credentials in a .env file or via environment variables when you run the server.

# Required
FIREWALLA_MSP_TOKEN=your_msp_access_token_here
FIREWALLA_MSP_ID=yourdomain.firewalla.net

# Optional - filters all queries to a specific box
FIREWALLA_BOX_ID=your_box_gid_here

# Build and start the MCP server (example using npm scripts if provided)
npm run build
npm run mcp:start

# Alternative: run with npx (production scenario)
npx firewalla-mcp-server

Transport options and how to configure them

The MCP server supports two transport modes: stdio (default) and HTTP transport.

# Stdio transport (default)
MCP_TRANSPORT=stdio

# HTTP transport (for external access)
MCP_TRANSPORT=http
MCP_HTTP_PORT=3000
MCP_HTTP_PATH=/mcp

Connect Claude Desktop or other MCP clients

If you install via npm, you can start the MCP server with the standard npx command during client setup.

npx firewalla-mcp-server

Next steps after setup

Once connected, begin with basic queries to verify alarms, network flows, and device status. Explore the 28 tools to perform security analysis, bandwidth monitoring, rule management, and target list operations. Use the advanced search features to filter results by type, time range, IP, and other attributes.

Available tools

get_active_alarms

Retrieve currently active security alarms and summarize their status.

get_specific_alarm

Fetch details for a single alarm by its identifier.

get_flow_data

Retrieve recent network flow records with optional filters.

get_bandwidth_usage

Identify top bandwidth users and overall usage patterns.

get_offline_devices

List devices that are currently offline.

get_device_status

Check the online/offline status of a given device.

get_boxes

List Firewalla boxes/units tied to the MSP account.

search_devices

Perform advanced searches across devices with filters and temporal queries.

get_network_rules

List firewall rules and their current state.

pause_rule

Temporarily pause a firewall rule without deleting it.

resume_rule

Resume a paused firewall rule.

get_target_lists

List security target lists and their categories.

create_target_list

Create a new security target list.

update_target_list

Update an existing target list.

delete_target_list

Delete a target list.

search_flows

Search network flows with complex queries and time ranges.

search_alarms

Search alarms using advanced filters and operators.

search_rules

Search firewall rules for insights on impact and performance.

search_target_lists

Search within target lists for matches and categories.

get_simple_statistics

Return high-level statistics and summaries for quick health checks.

get_flow_insights

Provide insights into traffic patterns by category and time.

get_flow_trends

Show trends in network flows over a period of time.

get_alarm_trends

Show trends in alarms and security events.

get_recent_flow_activity

Return a recent set of flow records to review recent activity.

get_top_devices_by_activity

Identify devices with the most network activity over a period.

get_geo_analysis

Enrich data with geographic information and risk indicators.