firewalla

The Firewalla MCP Server provides a bridge between MCP clients (like Claude Desktop, Claude Code, VS Code MCP extensions, and other MCP clients) and your Firewalla firewall data. It exposes 28 specialized tools for real-time firewall data, security analysis, bandwidth monitoring, rule management, target lists, and advanced search. The server translates client requests into Firewalla API calls and returns results in MCP-friendly formats. You can connect via the built-in stdio transport (default) for local or Claude Desktop usage, or run the server in HTTP transport mode within Docker or orchestration environments to support multiple external clients. Use the provided environment variables to authenticate with your MSP account and optionally scope queries to a single Firewalla box.

To get started, install the server (via npm/npx) and set your MSP credentials. Then configure your MCP client to point to the server using one of the transport modes. If you’re using Claude Desktop or Claude Code, the stdio transport is typical; for Docker deployments or remote access, enable HTTP transport and expose port as needed. The server presents the same 28 tools across clients, enabling you to query security alerts, analyze network flows, pause rules, manage target lists, and perform complex searches with filters and logical operators.

Prerequisites

• Node.js 18+ and npm
• Access to a Firewalla MSP account with API access
• A Firewalla device online and registered in MSP

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: Secrets may be visible in process lists. Prefer env-file for production.

# Run with stdio transport using environment variables (Linux/macOS example)
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
npm run mcp:start

Configure credentials

# Create a .env file or export variables in your environment
export FIREWALLA_MSP_TOKEN=your_msp_access_token_here
export FIREWALLA_MSP_ID=yourdomain.firewalla.net
export FIREWALLA_BOX_ID=your_box_gid_here   # Optional

Transport configuration (stdinio vs http)

# StdIO transport (default)
export MCP_TRANSPORT=stdio

# HTTP transport for external access
export MCP_TRANSPORT=http
export MCP_HTTP_PORT=3000   # default 3000
export MCP_HTTP_PATH=/mcp

Start the server

npm run build
npm run mcp:start

Tips and common considerations:

• If using HTTP transport, ensure proper network security (firewall rules, TLS termination if exposing publicly).
• For Claude Desktop integration, stdio transport is usually sufficient; use the default MCP_TRANSPORT=stdio setting.
• When using Docker, consider using an env-file to securely manage credentials and avoid exposing them in process listings.
• The MSP token and MSP ID are required; the optional BOX_ID can limit data to a specific Firewalla box.
• If you encounter 401/403 errors, verify that your MSP credentials are correct and that the MSP has access to the target devices.
• The README shows examples for connecting via npm (npx), Docker, and source installs; pick the method that best fits your deployment scenario.
• If you plan to run multiple MCP clients against the same server, prefer HTTP transport to share a single server instance.