Skip to main content
Glama

firewalla-mcp-server

by amittell
npmGitHub
TypeScript
MIT License
230
6
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

ClientQuick StartFull Guide
Claude Desktopnpm i -g firewalla-mcp-server → Configure MCPSetup Guide
Claude Codenpm i -g firewalla-mcp-server → CLI integrationSetup Guide
VS CodeInstall MCP extension → Configure serverSetup Guide
CursorInstall Claude Code → VSIX methodSetup Guide
RoocodeInstall MCP support → Configure serverSetup Guide
ClineConfigure in VS Code → Enable MCPSetup 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

# 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

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:

GitHub Repository

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

Repository Stats

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Provides comprehensive Firewalla MSP firewall integration via MCP protocol with 28 tools for real-time security monitoring, network analysis, bandwidth tracking, and rule management. Supports all MCP-compatible clients for automated network security operations.

  1. Why Firewalla MCP Server?
    1. Simple Network Security Integration
  2. Features
    1. Client Setup Guides
      1. How It Works
        1. Prerequisites
          1. Quick Start
            1. 1. Installation
            2. Option A: Install from npm (Recommended)
            3. Option B: Use Docker
            4. Option C: Install from source
            5. 2. Configuration
            6. 3. Build and Start
            7. 4. Connect Claude Desktop
            8. 5. Next Steps
          2. Usage Examples
            1. Step-by-Step First Use
            2. Practical Workflows
            3. Advanced Search Examples
            4. Troubleshooting Common Issues
          3. Available Tools (28 total)
            1. Core Tools
            2. Quick Reference
          4. Development
            1. Scripts
            2. MCP Execution Methods
            3. Project Structure
          5. Documentation
            1. Security
              1. Known Behaviors and Limitations
                1. Category Classification
                2. Data Characteristics
                3. API Limitations
              2. Troubleshooting
                1. Quick Fixes
                2. Debug Mode
              3. Contributing
                1. What's New
                  1. License
                    1. Support
                      1. GitHub Repository
                        1. Quick Links
                        2. Repository Stats

                      Related MCP Servers

                      • Semgrep MCP Serverofficial

                        semgrep
                        A
                        security
                        A
                        license
                        A
                        quality
                        An MCP server that provides a comprehensive interface to Semgrep, enabling users to scan code for security vulnerabilities, create custom rules, and analyze scan results through the Model Context Protocol.
                        Last updated -
                        6
                        226
                        Python
                        MIT License
                        • Linux
                        • Apple

                      • FFmpeg MCP Server

                        ZizoTheDev
                        A
                        security
                        F
                        license
                        A
                        quality
                        An MCP server designed to work with FFmpeg for media processing tasks, offering enhanced performance and secure communication for handling media processing requests.
                        Last updated -
                        2
                        14
                        11
                        TypeScript

                      • Alpaca MCP Server

                        cesarvarela
                        A
                        security
                        F
                        license
                        A
                        quality
                        MCP server that exposes Alpaca Market Data & Broker API as tools, enabling access to financial data like stock bars, assets, market days, and news through the Message Control Protocol.
                        Last updated -
                        4
                        11
                        2
                        TypeScript

                      View all related MCP servers

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/amittell/firewalla-mcp-server'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server