firewalla-mcp-server
Advanced tools
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
A Model Context Protocol (MCP) server that provides real-time access to Firewalla firewall data through 28 specialized tools, compatible with any MCP client.
| 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 |
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.
# Install globally
npm install -g firewalla-mcp-server
# Or install locally in your project
npm install firewalla-mcp-server
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:
--env-file with a .env file: docker run --env-file .env ...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
git clone https://github.com/amittell/firewalla-mcp-server.git
cd firewalla-mcp-server
npm install
npm run build
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:
https://yourdomain.firewalla.netcompany123.firewalla.net)get_boxes toolThe 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:
When to use stdio transport:
npm run build
npm run mcp:start
Add this configuration to your Claude Desktop claude_desktop_config.json:
{
"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"
}
}
}
}
{
"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"
]
}
}
}
{
"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:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json1. 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
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"
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
Connection Problems: If you get authentication errors:
.env file has correct credentialsEmpty Results: If queries return no data:
Performance Issues: If responses are slow:
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
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
Why npx for MCP servers?
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
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
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.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.Server won't start:
# Clean and rebuild
npm run clean
npm run build
# If build fails, try:
npm install
npm run build
Authentication errors:
No data returned:
Slow responses:
Enable detailed logging:
DEBUG=mcp:* npm run mcp:start
For more detailed troubleshooting, see TROUBLESHOOTING.md
Version 1.0.0:
For issues and questions:
Repository: https://github.com/amittell/firewalla-mcp-server
FAQs
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
The npm package firewalla-mcp-server receives a total of 22 weekly downloads. As such, firewalla-mcp-server popularity was classified as not popular.
We found that firewalla-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A malicious NuGet package impersonating Sicoob exfiltrated client IDs, PFX passwords, and banking certificates through Sentry telemetry.
Security News
Feross Aboukhadijeh joins TBPN to discuss Socket's $60M Series C, 500%+ ARR growth, AI's impact on open source, and the rise in supply chain attacks.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.
