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

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