firewalla-mcp-server

v1.2.2

Published

a month ago

Model Context Protocol (MCP) server for Firewalla MSP API - Provides real-time network monitoring, security analysis, and firewall management through 28 specialized tools compatible with any MCP client

Downloads

433

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 (minimal config)
docker run -it --rm \
  -e FIREWALLA_MSP_TOKEN=your_token \
  -e FIREWALLA_MSP_ID=yourdomain.firewalla.net \
  amittell/firewalla-mcp-server

# Or with optional box filter
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 \
  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 \
  amittell/firewalla-mcp-server

# Add FIREWALLA_BOX_ID if you want to filter to a specific box
# -e FIREWALLA_BOX_ID=your_box_gid \

# 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}
      # Optional: filter to specific box
      # - 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:

Log into your Firewalla MSP portal at https://yourdomain.firewalla.net
Your MSP ID is the full domain (e.g., company123.firewalla.net)
Generate an access token in API settings
(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 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:

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

Empty Results: If queries return no data:

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

Performance Issues: If responses are slow:

Reduce the limit parameter in queries
Use more specific time ranges
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Run the test suite
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