MCP Servers

A collection of Model Context Protocol (MCP) servers for network security and monitoring.

Servers

Firewalla MCP Server

A comprehensive MCP server for interacting with Firewalla network security devices. Provides network monitoring, device management, and security rule configuration through MCP tools.

Features

• Network Monitoring: Query network flows, analyze traffic patterns, detect security events
• Device Management: List, search, and get details for all network devices
• Security Rules: Allow/block/deny categories, apps, or specific targets per device
• Traffic Analysis: Top talkers, blocked traffic, protocol distribution, country stats
• Trend Data: 24h/7d/30d traffic trends with peak detection

Installation

cd firewalla
npm install
npm run build

Configuration

Option 1: Environment Variables (Recommended)

export FIREWALLA_URL="https://my.firewalla.com"
export FIREWALLA_TOKEN="your-bearer-token"
export FIREWALLA_ID="your-firewalla-device-id"
export LOG_LEVEL="info"  # debug, info, warn, error

Option 2: Runtime Configuration Use the configure_firewalla MCP tool after connecting.

Usage

# Start the server
npm run start

# Development mode (build + run)
npm run dev

Available MCP Tools

Tool	Description
configure_firewalla	Set API credentials (or use env vars)
get_config_status	Check configuration status and source
query_network_flows	Query network flows with time filters
list_devices	List all network devices
get_device_details	Get device info by MAC address
analyze_network_traffic	Traffic analysis (summary, top talkers, blocked, security)
get_device_traffic	Per-device traffic analysis
get_network_overview	Comprehensive network overview
get_cloud_rules	Active cloud security rules
get_traffic_trends	Traffic trends (24h/7d/30d)
get_firewalla_status	Firewalla device status
search_devices	Search devices by name/IP/MAC
update_device_rules	Modify device security rules

Development

Commands

npm run build          # Compile TypeScript
npm run start          # Run the server
npm run dev            # Build and run
npm test               # Run tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Run tests with coverage

Testing

The project uses Vitest for testing with 32 tests covering:

• API client functionality
• Error recovery and retry logic
• Environment variable configuration
• Structured logging
• Custom error classes

Architecture

firewalla/
├── server.ts          # Main server implementation
├── server.test.ts     # Test suite
├── vitest.config.ts   # Test configuration
├── package.json       # Dependencies
└── api_samples/       # Reference API responses

Key Components

• Logger: Structured JSON logging to stderr with configurable levels
• FirewallaAPI: HTTP client with retry logic and exponential backoff
• FirewallaMCPServer: MCP server with 13 tools for Firewalla interaction
• Error Classes: FirewallaAPIError, FirewallaAuthError, FirewallaNetworkError, FirewallaRateLimitError

Error Recovery

The API client includes robust error handling:

• Automatic retry on 5xx errors and network failures
• Exponential backoff with jitter
• Rate limit handling with Retry-After support
• Request timeouts (30s default)
• Configurable retry settings

Logging

Structured JSON logs to stderr (stdout reserved for MCP):

{"service":"firewalla-mcp","timestamp":"...","level":"info","message":"Server started","context":{"transport":"stdio"}}

License

MIT