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

# 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

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:

FIREWALLA_MSP_TOKEN=your_msp_access_token_here
FIREWALLA_MSP_ID=yourdomain.firewalla.net
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. Find your Box GID (Group ID) in device settings - this is your unique device identifier

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 firewall rules that blocked the most connections this week"

Uses: get_network_rules + search_flows for blocked traffic analysis

Device Behavior Analysis:

"Find all devices that were online yesterday but are offline now"

Uses: search_devices with temporal queries + get_offline_devices

Troubleshooting Common Issues

Connection Problems: If you get authentication errors:

1. Verify your .env file has correct credentials
2. Check your MSP token hasn't expired
3. Confirm your Box ID is the full GID format

Empty Results: If queries return no data:

1. Check your Firewalla is online and reporting
2. Verify the time range isn't too narrow
3. Try broader search terms first

Performance Issues: If responses are slow:

1. Reduce the limit parameter in queries
2. Use more specific time ranges
3. Check your network connection to the MSP API

Available Tools (28 total)

Core Tools

• Security: Get alarms, analyze threats
• Network: Monitor traffic flows, track bandwidth usage
• Devices: Check device status, find offline devices
• Rules: Manage firewall rules, pause/resume rules
• Search: Advanced search across all data types
• Analytics: Statistics, trends, and geographic analysis
• Target Management: Create, update, and delete security target lists

Quick Reference

Security: get_active_alarms, get_specific_alarm
Network: get_flow_data, get_bandwidth_usage, get_offline_devices  
Devices: get_device_status, get_boxes, search_devices
Rules: get_network_rules, pause_rule, resume_rule, get_target_lists
Search: search_flows, search_alarms, search_rules, search_target_lists
Analytics: get_simple_statistics, get_flow_insights, get_flow_trends, get_alarm_trends
Management: create_target_list, update_target_list, delete_target_list

Development

Scripts

npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run test         # Run all tests
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues

MCP Execution Methods

Why npx for MCP servers?

• Version Management: Always uses the correct/latest version
• Dependency Resolution: Handles package dependencies automatically
• No global installation required: Works without global installation
• MCP Standard: Follows Model Context Protocol conventions
• Reliable: Works consistently across different environments

Alternative execution methods:

# Development (from source)
npm run mcp:start

# Production (npm installed)
npx firewalla-mcp-server

# Direct execution (from source after build)
node dist/server.js

Project Structure

firewalla-mcp-server/
├── src/
│   ├── server.ts           # Main MCP server
│   ├── firewalla/          # Firewalla API client
│   ├── tools/              # MCP tool implementations
│   ├── resources/          # MCP resource implementations
│   └── prompts/            # MCP prompt implementations
├── tests/                  # Test files
├── docs/
│   └── firewalla-api-reference.md  # API documentation
├── CLAUDE.md              # Comprehensive development guide
├── SPEC.md                # Technical specifications
└── README.md              # This file

Documentation

• README.md (this file) - Setup and basic usage
• USAGE.md - Simple usage guide with examples
• TROUBLESHOOTING.md - Common issues and solutions
• docs/clients/ - Client-specific setup guides
• CLAUDE.md - Development guide and commands

Security

• MSP tokens are stored securely in environment variables
• No credentials are logged or stored in code
• Rate limiting prevents API abuse
• Input validation prevents injection attacks
• All API communications use HTTPS

Known Behaviors and Limitations

Category Classification

• Flow Categories: Many network flows may show as empty category ("") in the Firewalla API response. This is expected behavior - Firewalla categorizes traffic when it recognizes the domain/service (e.g., "av" for audio/video, "social" for social media).
• Target List Categories: Some target lists may show category as "unknown". This is normal for user-created or certain system lists.
• Timeline: Category classification happens at the Firewalla device level and may take time to build up meaningful categorization data.

Data Characteristics

• Response Sizes: The get_recent_flow_activity tool returns up to 150 recent flows to stay within token limits. For larger datasets or historical analysis, use search_flows with time filters for more targeted queries.
• Geographic Data: IP geolocation is enriched by the MCP server and includes country, city, and risk scores when available.

API Limitations

• Alarm Deletion: The delete_alarm tool may not actually delete alarms even though the Firewalla API returns a success response. This appears to be a limitation of the MSP API where delete operations return {"message": "success", "success": true} but the alarm remains in the system. This may be due to permission restrictions or API design.

Troubleshooting

Quick Fixes

Server won't start:

# Clean and rebuild
npm run clean
npm run build

# If build fails, try:
npm install
npm run build

Authentication errors:

• Check your MSP token is valid
• Verify Box ID format (long UUID)
• Confirm MSP domain is correct

No data returned:

• Try broader queries: "last week" vs "last hour"
• Check if Firewalla is online
• Test with: "show me basic statistics"

Slow responses:

• Add limits: "top 10 devices"
• Use shorter time ranges
• Restart the server

Debug Mode

Enable detailed logging:

DEBUG=mcp:* npm run mcp:start

For more detailed troubleshooting, see TROUBLESHOOTING.md

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

What's New

Version 1.0.0:

• 28 tools with API-verified schemas
• 24 direct API endpoints + 5 convenience wrappers
• NEW: get_flow_insights for category-based traffic analysis
• Advanced search with logical operators (AND, OR, NOT)
• All limits corrected to API maximum (500)
• Required parameters added for proper API calls
• Better caching for faster responses
• Handles high-volume networks (300k+ flows/day)

License

MIT License

Support

For issues and questions:

• Check the troubleshooting guide
• Review the technical specifications
• Open an issue on GitHub

---

GitHub Repository

Repository: https://github.com/amittell/firewalla-mcp-server

Quick Links

• Issues
• Pull Requests
• Actions
• Security

Repository Stats