Firewalla MSP MCP Server

A Model Context Protocol (MCP) server that provides access to the Firewalla Managed Service Provider (MSP) API. This server enables AI assistants and other MCP clients to interact with Firewalla MSP resources including boxes, devices, alarms, rules, flows, and target lists.

Features

- Complete API Coverage: Full CRUD operations for all Firewalla MSP API endpoints
- Advanced Search: Global search across devices, alarms, rules, flows, and boxes
- Analytics & Insights: Network statistics, historical trends, and performance metrics
- Security Management: Create, modify, and monitor security rules and alarms
- Network Monitoring: Real-time flow analysis and device tracking
- Target Lists: Manage IP/domain allow/block lists
- Secure Authentication: API token-based authentication
- Smart Pagination: Cursor-based pagination for large datasets
- Comprehensive Testing: Extensive test suite with safe read-only validation
- Type Safety: Full TypeScript support with complete type definitions
- Error Handling: Robust error handling and recovery mechanisms

Installation

``bash
npm install -g @unknown-sh/firewalla-msp-mcp-server
`

Or install locally in your project:

`bash
npm install @unknown-sh/firewalla-msp-mcp-server
`

Configuration

$3

The server requires two environment variables to be set:

- FIREWALLA_MSP_API_KEY: Your Firewalla MSP personal access token
- FIREWALLA_MSP_DOMAIN: Your MSP domain (e.g., your-company.firewalla.net)

$3

1. Log in to your Firewalla MSP portal
2. Navigate to Account Settings
3. Create a new personal access token
4. Note your MSP domain from the URL

$3

#### 1. Claude Desktop

Add to your Claude Desktop configuration file:

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

`json
{
"mcpServers": {
"firewalla-msp": {
"command": "npx",
"args": ["@unknown-sh/firewalla-msp-mcp-server"],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

#### 2. Claude Code

Add the MCP server using the Claude Code CLI:

`bash
claude mcp add firewalla-msp -e FIREWALLA_MSP_API_KEY=your-api-key-here -e FIREWALLA_MSP_DOMAIN=your-domain.firewalla.net -- npx @unknown-sh/firewalla-msp-mcp-server
`

Or if you have the server installed globally:

`bash
claude mcp add firewalla-msp -e FIREWALLA_MSP_API_KEY=your-api-key-here -e FIREWALLA_MSP_DOMAIN=your-domain.firewalla.net -- firewalla-msp-mcp-server
`

#### 3. Gemini-CLI

Add to ~/.config/gemini-cli/config.json:

`json
{
"mcpServers": {
"firewalla-msp": {
"command": "npx",
"args": ["@unknown-sh/firewalla-msp-mcp-server"],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

#### 4. Cursor

Add to your Cursor settings file:

macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor-ai.cursor-chat/config/mcp.json
Windows: %APPDATA%\Cursor\User\globalStorage\cursor-ai.cursor-chat\config\mcp.json

`json
{
"mcpServers": {
"firewalla-msp": {
"command": "npx",
"args": ["@unknown-sh/firewalla-msp-mcp-server"],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

#### 5. Windsurf (Codeium)

Add to Windsurf's MCP configuration:

macOS: ~/Library/Application Support/Windsurf/mcp.json
Windows: %APPDATA%\Windsurf\mcp.json

`json
{
"mcpServers": {
"firewalla-msp": {
"command": "npx",
"args": ["@unknown-sh/firewalla-msp-mcp-server"],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

#### 6. VS Code (via Continue or other MCP extensions)

For Continue extension, add to ~/.continue/config.json:

`json
{
"models": [
// Your existing models
],
"mcpServers": {
"firewalla-msp": {
"command": "npx",
"args": ["@unknown-sh/firewalla-msp-mcp-server"],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

#### Local Installation Alternative

If you prefer to install the server locally instead of using npx:

`bash
npm install -g @unknown-sh/firewalla-msp-mcp-server
`

Then use this configuration (same for all clients):

`json
{
"mcpServers": {
"firewalla-msp": {
"command": "firewalla-msp-mcp-server",
"args": [],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

#### Development Installation

For development or local testing, use absolute paths:

`json
{
"mcpServers": {
"firewalla-msp": {
"command": "node",
"args": ["/absolute/path/to/firewalla-msp-mcp-server/dist/index.js"],
"env": {
"FIREWALLA_MSP_API_KEY": "your-api-key-here",
"FIREWALLA_MSP_DOMAIN": "your-domain.firewalla.net"
}
}
}
}
`

Note: After adding the configuration, restart the respective application for changes to take effect.

Available Tools

The server provides 26 tools across 8 API categories for comprehensive Firewalla MSP management:

$3

- list_boxes - Get all Firewalla boxes in the MSP
- Optional: group - Filter by group ID

$3

- list_devices - Get all devices across boxes
- Optional: box - Filter by specific box ID
- Optional: group - Filter by specific box group ID

$3

- list_alarms - Get alarms with optional filtering
- Optional: query - Search query (e.g., 'status:active box:boxId type:9')
- Optional: groupBy - Group results (comma-separated)
- Optional: sortBy - Sort results (e.g., 'ts:desc,total:asc')
- Optional: limit - Max results per page (≤500, default 200)
- Optional: cursor - Pagination cursor

- get_alarm - Get a specific alarm
- Required: gid - Box GID
- Required: aid - Alarm ID

- delete_alarm - Delete a specific alarm
- Required: gid - Box GID
- Required: aid - Alarm ID

$3

- list_rules - Get all rules (requires MSP 2.7.0+)
- Optional: query - Search query (e.g., 'status:active box.id:boxId')

- create_rule - Create a new security rule
- Required: action - Rule action: allow, block, time_limit
- Required: direction - Traffic direction: inbound, outbound, bidirection
- Required: protocol - Protocol type: tcp, udp, icmp, any
- Required: target - Rule target specification:
- type - Target type: ip, domain, category, device, network
- value - Target value (IP, domain, etc.)
- Optional: name - Rule name (auto-generated if not provided)
- Optional: scope - Rule scope specification
- Optional: schedule - Rule schedule (for time_limit rules)

- update_rule - Update an existing rule
- Required: id - Rule ID
- Optional: All fields from create_rule
- Optional: status - Rule status: active, paused

- delete_rule - Delete a security rule
- Required: id - Rule ID

- pause_rule - Pause a specific rule
- Required: id - Rule ID

- resume_rule - Resume a paused rule
- Required: id - Rule ID

$3

- list_flows - Get network flows with filtering
- Optional: query - Search query (e.g., 'ts:1234567890-1234567899 box.id:boxId')
- Optional: groupBy - Group results
- Optional: sortBy - Sort results (default: 'ts:desc')
- Optional: limit - Max results per page (≤500, default 200)
- Optional: cursor - Pagination cursor

$3

- list_target_lists - Get all target lists

- get_target_list - Get a specific target list
- Required: id - Target list ID

- create_target_list - Create a new target list
- Required: name - Name of the target list
- Required: targets - Array of IP addresses or domains
- Optional: owner - Owner of the target list
- Optional: category - Category of the target list
- Optional: notes - Notes about the target list

- update_target_list - Update an existing target list
- Required: id - Target list ID
- Optional: name - Name of the target list
- Optional: targets - Array of IP addresses or domains
- Optional: owner - Owner of the target list
- Optional: category - Category of the target list
- Optional: notes - Notes about the target list

- delete_target_list - Delete a target list
- Required: id - Target list ID

$3

- get_simple_statistics - Get overview statistics (boxes, alarms, rules counts)
- Optional: group - Filter by specific box group ID

- get_statistics - Get detailed statistics by type
- Required: type - Statistics type:
- topBoxesByBlockedFlows - Top boxes by blocked flows
- topBoxesBySecurityAlarms - Top boxes by security alarms
- topRegionsByBlockedFlows - Top regions by blocked flows
- Optional: group - Filter by specific box group ID
- Optional: limit - Maximum results (1-50, default: 5)

$3

- get_trends - Get historical trend data over time
- Required: type - Trend data type:
- flows - Daily blocked flows trends
- alarms - Daily security alarms trends
- rules - Daily rule creation trends
- Optional: group - Filter by specific box group ID

$3

Based on comprehensive API testing, search is supported on 4 out of 8 data model types using Firewalla's advanced query syntax.

#### Supported Search Types
- Devices - Full text search and device-specific qualifiers
- Alarms - Advanced filtering with alarm-specific qualifiers
- Flows - Comprehensive search with flow-specific qualifiers
- Boxes - Basic query support

#### Search Tools

- search_global - Search across all searchable entity types
- Required: query - Search query using Firewalla syntax
- Optional: types - Array of entity types: ["devices", "alarms", "flows", "boxes"]
- Optional: limit - Max results per type (1-500, default: 10)
- Optional: cursor - Pagination cursor for continuing results

- search_devices - Search devices with device-specific qualifiers
- Required: query - Search query with qualifiers: device.name, device.id, box.id, box.name, box.group.id
- Optional: limit - Maximum results (1-500, default: 50)
- Optional: cursor - Pagination cursor

- search_alarms - Search alarms with alarm-specific qualifiers
- Required: query - Search query with qualifiers: ts, type, status, box.id, box.name, box.group.id, device.id, device.name, remote.category, remote.domain, remote.region, transfer.download, transfer.upload, transfer.total
- Optional: limit - Maximum results (1-500, default: 50)
- Optional: cursor - Pagination cursor

- search_flows - Search flows with flow-specific qualifiers
- Required: query - Search query with qualifiers: ts, status, direction, box.id, box.name, box.group.id, device.id, device.name, category, domain, region, sport, dport, download, upload, total
- Optional: limit - Maximum results (1-500, default: 50)
- Optional: cursor - Pagination cursor

#### Query Syntax

Firewalla search supports advanced query syntax:

Basic Text Search:
`
"iPhone"
"MacBook Pro"
apple
`

Qualified Search:
`
status:active
device.name:iPhone
box.name:"Gold Plus"
`

Wildcard Search:
`
device.name:iphone
domain:*.google.com
`

Numeric Comparisons:
`
ts:>1720000000
download:>1MB
total:>=500KB
transfer.total:<100MB
`

Range Search:
`
ts:1720000000-1720086400
download:100KB-1MB
`

Combined Queries:
`
status:active type:1
direction:outbound domain:google
device.name:iphone ts:>1720000000
`

Exclusion Search:
`
-status:resolved
-type:1
`

#### Supported Units
- B (Byte)
- KB (1000 B)
- MB (1000 KB)
- GB (1000 MB)
- TB (1000 GB)

#### Timestamp Format
Use Unix timestamps (seconds since epoch):
`
ts:>1720000000 # After specific time
ts:1720000000-1720086400 # Time range
`

#### Non-Searchable Types
These endpoints do not support search queries:
- Target Lists (list_target_lists)
- Statistics (get_statistics, get_simple_statistics)
- Trends (get_trends)

Query Syntax

Many endpoints support advanced querying using specific qualifiers:

$3


- ts - Timestamp
- type - Alarm type
- status - Alarm status (active/archived)
- box.id - Box ID
- box.name - Box name
- device.id - Device ID
- device.name - Device name
- remote.category - Remote category
- remote.domain - Remote domain
- transfer.download - Download amount
- transfer.upload - Upload amount
- transfer.total - Total transfer

$3

- ts - Timestamp
- status - Flow status
- direction - Traffic direction
- box.id - Box ID
- box.name - Box name
- device.id - Device ID
- device.name - Device name
- category - Flow category
- domain - Domain
- region - Geographic region
- sport - Source port
- dport - Destination port
- download - Download amount
- upload - Upload amount
- total - Total traffic

$3

- status - Rule status
- action - Rule action
- box.id - Box ID
- box.group.id - Box group ID
- device.id - Device ID

Examples

$3

Once configured, you can ask Claude to interact with your Firewalla MSP:

`
"List all active alarms from the last 24 hours"
"Show me all devices that are currently offline"
"Create a new target list with suspicious IP addresses"
"Pause all rules on box xyz123"
`

$3

`javascript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
command: "npx",
args: ["@unknown-sh/firewalla-msp-mcp-server"],
env: {
FIREWALLA_MSP_API_KEY: "your-api-key",
FIREWALLA_MSP_DOMAIN: "your-domain.firewalla.net"
}
});

const client = new Client({
name: "firewalla-client",
version: "1.0.0"
}, {
capabilities: {}
});

await client.connect(transport);

// List all boxes
const result = await client.callTool({
name: "list_boxes",
arguments: {}
});

console.log(result);
`

Testing

The server includes comprehensive test scripts to validate all API functionality:

$3

All test scripts are located in the tests/ directory and can be run individually:

`bash
cd tests

Safe read-only test (recommended first test)

node test-readonly.js

Search API functionality

node test-search.js

Statistics API tests

node test-statistics.js

Trends API tests

node test-trends.js

Rules CRUD operations (modifies your Firewalla)

node test-rules-crud.js

Basic server connectivity

node test-server.js
`

$3

- test-readonly.js - Safe read-only operations across all APIs (boxes, devices, alarms, rules, target lists)
- test-search.js - Global search functionality across all entity types with filtering
- test-statistics.js - Network statistics including top boxes, regions, and overview data
- test-trends.js - Historical trend analysis for flows, alarms, and rules
- test-rules-crud.js - Complete CRUD operations for security rules (use with caution)
- test-server.js - Basic MCP server connectivity and tool listing

$3

For convenience, run all safe tests at once:

`bash
cd tests
./run-all-tests.sh
`

This runs all read-only tests in sequence and provides a comprehensive validation of the MCP server functionality.

$3

⚠️ Important:
- Start with test-readonly.js to verify your setup safely
- test-rules-crud.js modifies your Firewalla configuration - use carefully
- All other tests are read-only and safe to run
- The test runner (run-all-tests.sh) excludes write operations for safety

Development

To run the server in development mode:

`bash


Clone the repository

git clone https://github.com/your-username/firewalla-msp-mcp-server.git
cd firewalla-msp-mcp-server

Install dependencies

npm install

Set environment variables

export FIREWALLA_MSP_API_KEY="your-api-key"
export FIREWALLA_MSP_DOMAIN="your-domain.firewalla.net"

Run in development mode

npm run dev

Build the project

npm run build

Run tests

npm test
`

Security Considerations

- Never commit your API key to version control
- Use environment variables or secure credential management
- The API key provides full access to your MSP account - keep it secure
- Consider using read-only tokens if you only need to query data

Error Handling

The server provides detailed error messages for common issues:

- 401 Unauthorized - Check your API key
- 404 Not Found - Resource doesn't exist
- 400 Bad Request - Invalid parameters or query syntax

License

GNU General Public License v3.0

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See the LICENSE file for the full license text.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

When contributing:
1. Ensure all tests pass (cd tests && ./run-all-tests.sh`)
2. Add tests for new functionality
3. Update documentation
4. Follow existing code style

Support

For issues related to:
- This MCP server: Open an issue on GitHub
- Firewalla MSP API: Contact help@firewalla.com
- MCP protocol: See the MCP documentation

Disclaimer

This is an independent, open-source MCP server implementation for the Firewalla MSP API.

Important: This project is:
- ✅ Independent: Created and maintained by the open-source community
- ✅ Unofficial: Not affiliated with, endorsed by, or developed by Firewalla Inc.
- ✅ Open Source: Licensed under GNU GPL v3.0
- ✅ Community-Driven: Contributions and feedback welcome

Firewalla® is a trademark of Firewalla Inc. The use of this trademark in this project is purely for descriptive purposes to indicate compatibility and does not imply any official relationship or endorsement.