Firewalla

You are running the Firewalla MCP Server to access Firewalla firewall data in real time through a set of 28 MCP tools. This server acts as a bridge between your Firewalla device and MCP clients, translating client requests into Firewalla API calls and returning results in MCP-compatible formats. It enables secure, API-driven monitoring, analysis, and management workflows for security, networking, devices, rules, and searches.

How to use

Connect an MCP client (such as Claude Desktop, Claude Code, or an MCP-enabled editor) to the Firewalla MCP Server. You will run the MCP server locally or in a container, then point your MCP client to the appropriate runtime configuration to start querying alarms, flows, devices, rules, and searches. Practical workflows include daily security reviews, investigating suspicious activity, network troubleshooting, and bandwidth analysis. Use the provided prompts and natural language queries to retrieve data and insights from your Firewalla firewall.

Common usage patterns include: verifying connectivity, running security overviews, and performing advanced searches across alarms, flows, and devices. You can also query for insights like top bandwidth users, online/offline devices, and the status of critical firewall rules. When device names or IPs appear, you’ll see related flows, blocks, and possible rule blocks that help you triage issues quickly.

How to install

Prerequisites you need before starting: Node.js 18+ and npm, a Firewalla MSP account with API access, and your Firewalla device online.

Option A: Install from npm (Recommended)

# Install globally
npm install -g firewalla-mcp-server

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

Option B: Use Docker

Warning: Not for production use – secrets visible in process list. Prefer secure alternatives for credentials in production.

# Using Docker Hub image
docker run -it --rm \
  -e FIREWALLA_MSP_TOKEN=your_token \
  -e FIREWALLA_MSP_ID=yourdomain.firewalla.net \
  -e FIREWALLA_BOX_ID=your_box_gid \
  amittell/firewalla-mcp-server

# Or build locally
docker build -t firewalla-mcp-server .
docker run -it --rm \
  -e FIREWALLA_MSP_TOKEN=your_token \
  -e FIREWALLA_MSP_ID=yourdomain.firewalla.net \
  -e FIREWALLA_BOX_ID=your_box_gid \
  firewalla-mcp-server

Option C: Install from source

git clone https://github.com/amittell/firewalla-mcp-server.git
cd firewalla-mcp-server
npm install
npm run build

Configuration and start

Create a credentials file with your Firewalla MSP access details to authenticate with the MSP API.

Environment variables to set (examples shown):

FIREWALLA_MSP_TOKEN=your_msp_access_token_here
FIREWALLA_MSP_ID=yourdomain.firewalla.net
FIREWALLA_BOX_ID=your_box_gid_here

Start the MCP server after building. Use one of the approved runtime commands listed below. Pick the method that matches how you installed the server.

Production-style start (via npm installed package)

npm run mcp:start

Direct execution from a built source (via Node)

node dist/server.js

Connect Claude Desktop configuration

Configure your MCP client to load the Firewalla server as shown in the examples below. Use environment variables to supply credentials.

If you installed via npm, use this MCP server configuration block in your client settings

{
  "mcpServers": {
    "firewalla": {
      "command": "npx",
      "args": ["firewalla-mcp-server"],
      "env": {
        "FIREWALLA_MSP_TOKEN": "your_msp_access_token_here",
        "FIREWALLA_MSP_ID": "yourdomain.firewalla.net",
        "FIREWALLA_BOX_ID": "your_box_gid_here"
      }
    }
  }
}

Next steps

If you want deeper usage, review practical examples and common queries to get familiar with the available tools and data. Start with basic health checks, then explore security alerts, flows, and device status to build comprehensive security and network insights.

Configuration notes and security

Store MSP tokens securely in environment variables and avoid logging credentials. The server uses HTTPS for API communications and enforces rate limiting to protect the API from abuse.

Known limitations include occasional empty flow categories and a caveat with alarm deletion that can appear successful at the API level but may not remove the alarm in all MSP contexts. Always verify results directly in Firewalla when performing critical cleanup.

Troubleshooting

Server won’t start: clean and rebuild, then try again.

Authentication errors: verify tokens, Box ID format, and MSP domain.

No data returned: broaden time ranges or verify that Firewalla is online.

Slow responses: reduce query limits and use shorter time ranges, then retry.

Available tools

get_active_alarms

Fetch current security alarms and events from Firewalla to assess threats and incidents.

get_specific_alarm

Retrieve details for a particular alarm by its identifier.

get_flow_data

Obtain real-time network flow information to analyze traffic patterns.

get_bandwidth_usage

Identify top bandwidth users and usage patterns over a given period.

get_offline_devices

List devices that have recently gone offline or are currently offline.

get_device_status

Check the current status of devices managed by Firewalla.

get_boxes

Query Firewalla boxes (gateways) and their status.

search_devices

Search devices by attributes and temporal queries to identify activity.

get_network_rules

View firewall rules and their current state (active/paused).

pause_rule

Temporarily pause a firewall rule to test impact or isolate issues.

resume_rule

Resume a paused firewall rule after testing.

get_target_lists

Manage target lists that categorize security-related entities.

search_flows

Advanced search across flows with filters and time ranges.

search_alarms

Advanced search for alarms using queries and filters.

search_rules

Search firewall rules based on attributes and history.

search_target_lists

Search through target lists for quick access.

get_simple_statistics

Obtain concise stats about activity, devices, and traffic.

get_flow_insights

Analyze traffic by category and behavior for insights.

get_flow_trends

Trends in network flows over time to spot anomalies.

get_alarm_trends

Trends in alarms and incidents over time.

create_target_list

Create a new security target list.

update_target_list

Update an existing target list by ID.

delete_target_list

Delete a target list from the system.