Firewalla MCP Server

A production-ready Model Context Protocol (MCP) server for Firewalla network management, designed to work seamlessly with Claude Desktop and other MCP-compatible clients.

✨ Features

🔒 Enterprise Security - Firewalla API keys never exposed to clients
🚀 Multi-Transport Support - stdio, SSE, and HTTP transports
📊 Comprehensive Monitoring - Device, network, and security analytics
🛡️ Built-in Protection - Rate limiting, input validation, audit logging
🐳 Docker-Ready - Production-grade containerized deployment
🔄 Resilient Architecture - Circuit breakers, retry logic, intelligent caching
🎯 14 Powerful Tools - Complete Firewalla management capabilities

🛠️ Available Tools

📱 Device Monitoring (3 tools)

get_devices - List all network devices with status and basic info
get_device_details - Detailed device information including bandwidth usage
search_devices - Search devices by name, IP, MAC, or vendor

🌐 Network Analysis (3 tools)

analyze_network_flows - Analyze traffic flows with filtering and statistics
get_bandwidth_statistics - Bandwidth usage stats for devices or entire network
get_network_statistics - Comprehensive network health and top talkers

🔐 Security Monitoring (4 tools)

get_alarms - Retrieve security alerts with severity and category filtering
get_alarm_details - Detailed information about specific security events
archive_alarm - Mark security alerts as reviewed
get_alarm_statistics - Statistical analysis of security events

⚙️ Rule Management (4 tools)

list_firewall_rules - List all firewall rules with status and conditions
get_rule_details - Detailed rule information including hit statistics
pause_rule - Temporarily disable rules with duration and reason
resume_rule - Re-enable paused firewall rules

🚀 Quick Start

Automated Setup (Recommended)

git clone https://github.com/MadLlama25/firewalla_msp-mcp.git
cd firewalla_msp-mcp
./scripts/setup.sh

The setup script will:

✅ Check prerequisites
✅ Create and configure environment files
✅ Build Docker image
✅ Generate Claude Desktop configuration
✅ Start the server

Manual Setup

Prerequisites

Docker and Docker Compose
Firewalla MSP account with API token
Claude Desktop (or other MCP client)
(Optional) Cloudflare Tunnel for remote access

Installation Steps

Clone and Setup

git clone https://github.com/MadLlama25/firewalla_msp-mcp.git
cd firewalla_msp-mcp
cp .env.example .env

Configure Environment Edit .env with your Firewalla credentials:

FIREWALLA_API_TOKEN=your_api_token_here
FIREWALLA_MSP_DOMAIN=https://your-domain.firewalla.net

Deploy with Docker Compose

docker-compose up -d

Verify Deployment

curl http://localhost:3000/health
docker logs firewalla-mcp

🔧 Claude Desktop Configuration

Local Docker (Recommended)

{
  "mcpServers": {
    "firewalla": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/full/path/to/.env",
        "--network", "host",
        "firewalla-mcp"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Remote Access via Cloudflare Tunnel

{
  "mcpServers": {
    "firewalla": {
      "url": "https://your-tunnel-domain.example.com/mcp",
      "transport": "sse"
    }
  }
}

Local HTTP (Alternative)

{
  "mcpServers": {
    "firewalla": {
      "url": "http://localhost:3000/mcp",
      "transport": "sse"
    }
  }
}

🏗️ Architecture

Security Architecture

API Key Isolation - Firewalla credentials stored securely in Docker
Request Validation - Comprehensive input sanitization and validation
Rate Limiting - Per-client request throttling
Audit Logging - Complete request/response audit trail
Circuit Breakers - Automatic failover when Firewalla API is unavailable

Performance Features

Intelligent Caching - Multi-tier caching with TTL
Connection Pooling - Optimized HTTP client with retry logic
Resource Management - Memory-efficient data processing
Health Monitoring - Built-in health checks and metrics

📁 Configuration Reference

Environment Variables

Variable	Required	Default	Description
`FIREWALLA_API_TOKEN`	✅	-	Your Firewalla MSP API token
`FIREWALLA_MSP_DOMAIN`	✅	-	Your MSP domain URL
`PORT`	❌	3000	Server port
`MCP_TRANSPORT`	❌	sse	Transport method (stdio/sse/http)
`LOG_LEVEL`	❌	info	Logging level (debug/info/warn/error)
`CACHE_ENABLED`	❌	true	Enable response caching
`RATE_LIMIT_MAX`	❌	100	Max requests per window

Docker Deployment Options

Production (docker-compose)

docker-compose up -d

Development (with hot reload)

docker-compose -f docker-compose.yml up firewalla-mcp-dev

Standalone Docker

docker run -d --name firewalla-mcp \
  --env-file .env \
  -p 3000:3000 \
  firewalla-mcp

🔍 Monitoring & Troubleshooting

Health Checks

# Server health
curl http://localhost:3000/health

# Container logs
docker logs firewalla-mcp

# Container status
docker ps | grep firewalla-mcp

Common Issues

Authentication Errors

Verify FIREWALLA_API_TOKEN is correct
Check FIREWALLA_MSP_DOMAIN format
Ensure API token has proper permissions

Connection Issues

Check Docker container is running
Verify port 3000 is accessible
Check Cloudflare Tunnel configuration (if using)

Performance Issues

Monitor cache hit rates in logs
Check circuit breaker status
Verify adequate system resources

🔒 Security Considerations

API Key Management

Store Firewalla API tokens in environment variables only
Never commit API keys to version control
Rotate API keys regularly (recommended: 90 days)
Use separate tokens for different environments

Network Security

Deploy behind Cloudflare Tunnel for production
Use HTTPS/TLS for all communications
Implement IP allowlisting if required
Monitor audit logs regularly

Access Control

Enable API key authentication for non-Claude Desktop clients
Use role-based permissions where applicable
Monitor unusual usage patterns
Implement automatic lockouts for suspicious activity

🤝 Multi-Client Support

Works with various MCP clients:

Claude Desktop - Primary target with optimized integration
Continue IDE - VS Code extension support
Custom MCP Clients - HTTP/SSE API available

🧪 Testing

Test Categories

Unit Tests - Core utilities, middleware, and individual components
Integration Tests - API client, caching, and service integration
MCP Tool Tests - All 14 Firewalla management tools
Security Tests - Input validation, sanitization, and vulnerability checks
Performance Tests - Load testing and performance benchmarks

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test categories
npm run test:unit
npm run test:integration
npm run test:security
npm run test:performance

# Run tests in watch mode
npm run test:watch

Test Coverage Targets

Unit Tests: 90% line coverage
Integration Tests: 80% path coverage
Critical Paths: 100% coverage (authentication, validation, security)

Quality Gates

All commits must pass:

✅ Linting (ESLint)
✅ Type checking (TypeScript)
✅ Unit tests (90%+ coverage)
✅ Security audit (npm audit)
✅ Code formatting (Prettier)

# Run pre-commit checks
npm run pre-commit
# or use the script
./scripts/pre-commit.sh

📝 Development

Local Development

npm install
npm run dev

Building

npm run build
npm run lint
npm run type-check

Testing Strategy

See TESTING_PLAN.md for comprehensive testing documentation.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests (maintain coverage targets)
Run pre-commit checks
Submit a pull request

Code Quality Standards

TypeScript strict mode enabled
ESLint with strict configuration
Prettier for consistent formatting
Jest for testing with high coverage
Security-first development practices

📊 Performance Metrics

Response Time - Sub-100ms for cached requests
Throughput - 1000+ requests per minute
Uptime - 99.9% with automatic recovery
Cache Hit Rate - 70-90% for typical workloads

📜 License

MIT License - see LICENSE file for details

🆘 Support

Issues - GitHub Issues
Documentation - Built-in API documentation
Logs - Comprehensive audit trail and error logging

Built with ❤️ for the Firewalla community

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

A production-ready server that connects Claude Desktop to Firewalla network management capabilities, allowing users to monitor devices, analyze network traffic, manage security alerts, and configure firewall rules through natural language.

Related MCP Servers

mcp-server-cloudflareofficial
cloudflare
A
security
A
license
A
quality
Lets you use Claude Desktop, or any MCP Client, to use natural language to accomplish things on your Cloudflare account.
Last updated -
2
1,486
2,785
TypeScript
Apache 2.0
MCP Web Research Server
jevy
A
security
A
license
A
quality
A server that integrates with Claude Desktop to enable real-time web research capabilities, allowing users to search Google, extract webpage content, and capture screenshots directly from conversations.
Last updated -
3
821
MIT License
Desktop Commander MCP
MrGNSS
A
security
A
license
A
quality
A server that lets Claude desktop app execute terminal commands on your computer and edit files through Model Context Protocol, featuring command execution, process management, and advanced file operations.
Last updated -
19
29,418
3
MIT License
OPNSense MCP Server
vespo92
A
security
A
license
A
quality
A server that enables managing OPNSense firewalls through natural language interactions with Claude Desktop, supporting VLAN management, firewall rules configuration, and network interface queries.
Last updated -
19
10
TypeScript
MIT License

View all related MCP servers