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

Related MCP server: MCP Web Research Server

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

1. Clone and Setup

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

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

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

3. Deploy with Docker Compose

docker-compose up -d

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

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

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