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)

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

1. Clone and Setup

2. Configure Environment Edit .env with your Firewalla credentials:

3. Deploy with Docker Compose

4. Verify Deployment

🔧 Claude Desktop Configuration

Local Docker (Recommended)

Remote Access via Cloudflare Tunnel

Local HTTP (Alternative)

🏗️ 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

Docker Deployment Options

Production (docker-compose)

Development (with hot reload)

Standalone Docker

🔍 Monitoring & Troubleshooting

Health Checks

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

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)

📝 Development

Local Development

Building

Testing Strategy

See TESTING_PLAN.md for comprehensive testing documentation.

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests (maintain coverage targets)

5. Run pre-commit checks

6. 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