amittell/firewalla-mcp-server

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

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: 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 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 for practical examples and common queries
• Check if you encounter issues
• Review client-specific setup guides in

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 (29 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
• - Simple usage guide with examples
• - 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

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:

• 29 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

Support

For issues and questions:

• Check the
• Review the
• Open an issue on GitHub

GitHub Repository

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

Quick Links

• Issues
• Pull Requests
• Actions
• Security

Repository Stats