Firewalla

Firewalla MCP Server

A Model Context Protocol (MCP) server that provides real-time access to Firewalla firewall data through 28 specialized tools, compatible with any MCP client.

Why Firewalla MCP Server?

Simple Network Security Integration

• 28 Tools for network monitoring and analysis
• 23 Direct API Endpoints + 5 Convenience Wrappers
• Advanced Search with query syntax and filters
• Clean, Verified Architecture with corrected API schemas

Features

• Real-time Firewall Data: Query security alerts, network flows, and device status
• Security Analysis: Get insights on threats, blocked attacks, and network anomalies
• Bandwidth Monitoring: Track top bandwidth consumers and usage patterns
• Rule Management: View and temporarily pause firewall rules
• Target Lists: Manage custom security target lists and categories
• Search Tools: Query syntax with filters and logical operators

Client Setup Guides

Client	Quick Start	Full Guide
Claude Desktop	npm i -g firewalla-mcp-server → Configure MCP	Setup Guide
Claude Code	npm i -g firewalla-mcp-server → CLI integration	Setup Guide
VS Code	Install MCP extension → Configure server	Setup Guide
Cursor	Install Claude Code → VSIX method	Setup Guide
Roocode	Install MCP support → Configure server	Setup Guide
Cline	Configure in VS Code → Enable MCP	Setup Guide

How It Works

Claude Desktop/Code ↔ MCP Server ↔ Firewalla API

The MCP server acts as a bridge between Claude and your Firewalla firewall, translating Claude's requests into Firewalla API calls and returning the results in a format Claude can understand.

Prerequisites

• Node.js 18+ and npm
• Firewalla MSP account with API access
• Your Firewalla device online and connected

Quick Start

1. Installation

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

The examples below pass credentials directly in the command line, which exposes them to process listing and shell history. For production use, consider these secure alternatives:

• Use --env-file with a .env file: docker run --env-file .env ...
• Set environment variables in your shell before running Docker
• Use Docker secrets for orchestration environments

Stdio Transport (Default - for Claude Desktop integration):

# 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

# Recommended: Using env file (more secure)
docker run -it --rm --env-file .env amittell/firewalla-mcp-server

HTTP Transport (for standalone Docker containers and external access):

# Run with HTTP transport on port 3000
docker run -d --name firewalla-mcp \
  -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_PORT=3000 \
  -e FIREWALLA_MSP_TOKEN=your_token \
  -e FIREWALLA_MSP_ID=yourdomain.firewalla.net \
  -e FIREWALLA_BOX_ID=your_box_gid \
  amittell/firewalla-mcp-server

# The server will be accessible at http://localhost:3000/mcp

# Using env file (recommended)
docker run -d --name firewalla-mcp \
  -p 3000:3000 \
  --env-file .env \
  amittell/firewalla-mcp-server

# For docker-compose
cat > docker-compose.yml << EOF
version: '3.8'
services:
  firewalla-mcp:
    image: amittell/firewalla-mcp-server
    ports:
      - "3000:3000"
    environment:
      - MCP_TRANSPORT=http
      - MCP_HTTP_PORT=3000
      - FIREWALLA_MSP_TOKEN=\${FIREWALLA_MSP_TOKEN}
      - FIREWALLA_MSP_ID=\${FIREWALLA_MSP_ID}
      - FIREWALLA_BOX_ID=\${FIREWALLA_BOX_ID}
    restart: unless-stopped
EOF

docker-compose up -d

Option C: Install from source

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

2. Configuration

Create a .env file with your Firewalla credentials:

# 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

Getting Your Credentials:

1. Log into your Firewalla MSP portal at https://yourdomain.firewalla.net
2. Your MSP ID is the full domain (e.g., company123.firewalla.net)
3. Generate an access token in API settings
4. (Optional) Find your Box GID in device settings to filter queries to a specific box, or retrieve available boxes using the get_boxes tool

Transport Configuration

The MCP server supports two transport modes:

Stdio Transport (Default): Standard input/output communication for Claude Desktop and similar MCP clients

MCP_TRANSPORT=stdio

HTTP Transport: HTTP server mode for Docker containers, MCP orchestrators, and external access

MCP_TRANSPORT=http
MCP_HTTP_PORT=3000          # Default: 3000
MCP_HTTP_PATH=/mcp          # Default: /mcp

When to use HTTP transport:

• Running in Docker containers independently
• Accessing from MCP orchestrators (e.g., open-webui)
• Multiple clients need to connect to the same server instance
• Network-based access to the MCP server

When to use stdio transport:

• Claude Desktop integration (default)
• Claude Code CLI integration
• Single-process MCP client setups
• Standard MCP client configurations

3. Build and Start

npm run build
npm run mcp:start

4. Connect Claude Desktop

Add this configuration to your Claude Desktop claude_desktop_config.json:

If installed via npm

{
  "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"
      }
    }
  }
}

If using Docker

{
  "mcpServers": {
    "firewalla": {
      "command": "docker",
      "args": ["run", "-i", "--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"
      ]
    }
  }
}

If installed from source

{
  "mcpServers": {
    "firewalla": {
      "command": "node",
      "args": ["/full/path/to/firewalla-mcp-server/dist/server.js"],
      "env": {
        "FIREWALLA_MSP_TOKEN": "your_msp_access_token_here",
        "FIREWALLA_MSP_ID": "yourdomain.firewalla.net",
        "FIREWALLA_BOX_ID": "your_box_gid_here"
      }
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

5. Next Steps

• See USAGE.md for practical examples and common queries
• Check TROUBLESHOOTING.md if you encounter issues
• Review client-specific setup guides in docs/clients/

Usage Examples

Step-by-Step First Use

1. Verify Connection After completing the setup, verify the MCP server is working:

# Start the server
npm run mcp:start

# You should see output like:
# MCP Server starting...
# Firewalla client initialized
# Server ready on stdio transport

2. Test with Claude Open Claude Desktop and try these starter queries:

Basic Health Check:

"Can you check my Firewalla status and show me a summary?"

This uses: firewall_summary resource + get_simple_statistics tool

Security Overview:

"What security alerts do I have? Show me the 5 most recent ones."

This uses: get_active_alarms tool with limit parameter

Practical Workflows

Daily Security Review:

"Give me today's security report. Include:
1. Any new security alerts
2. Top 3 devices using bandwidth
3. Any devices that went offline
4. Status of critical firewall rules"

Investigating Suspicious Activity:

"I noticed unusual traffic. Can you:
1. Show me all security and abnormal upload alarms from the last 4 hours
2. Find any blocked connections to external IPs
3. Check which devices had the most network activity"

Network Troubleshooting:

"A device seems to have connectivity issues. Can you:
1. Check if device 192.168.1.100 is online
2. Show its recent network flows
3. See if any rules are blocking its traffic"

Bandwidth Investigation:

"Our internet is slow. Help me find the cause:
1. Show top 10 bandwidth users in the last hour
2. Look for any devices with unusual upload/download patterns
3. Check for any streaming or video traffic"

Advanced Search Examples

Find Specific Threats:

search for: security activity alarms from IP range 10.0.0.* in the last 24 hours

Uses: search_alarms with query: "type:1 AND source_ip:10.0.0. AND timestamp:>24h"*

Analyze Rule Effectiveness:

"Show me fi

---

*README truncated. [View full README on GitHub](https://github.com/amittell/firewalla-mcp-server).*