firewalla-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

CRITICAL: Before Any API Development

READ FIRST: /docs/firewalla-api-reference.md - Complete Firewalla API specification

Key Rules:

• ONLY use endpoints documented in /docs/firewalla-api-reference.md
• NEVER assume endpoints exist without verification
• ALWAYS use box-specific routing: /v2/boxes/{box_gid}/{resource}
• NEVER use paths without the /v2/ prefix (/stats/simple, /trends/flows do not exist); the documented forms are /v2/stats/simple and /v2/trends/{flows,alarms,rules}
• /v2/alarms and /v2/flows refuse limit over 500 (HTTP 400); page with next_cursor
• Trends come from /v2/trends/{alarms,flows} (daily points; /v2/trends/rules answers 400, so rule trends count rule creation times on the days of /v2/trends/alarms); bandwidth is aggregated on the client from flows

Project Overview

A Model Context Protocol (MCP) server that provides Claude with access to Firewalla firewall data: 28 read-only tools by default, plus 11 opt-in write tools, with advanced search capabilities. By default no tool changes anything.

Architecture Overview

28 Read-Only Tools, 11 Opt-In Write Tools

• 23 Direct API Tools: Mapping to Firewalla MSP API endpoints (read-only)
• 5 Convenience Wrapper Tools: Client-side enhanced functionality for common operations (read-only)
• 11 Write Tools: Create, update, pause and delete operations, registered only with FIREWALLA_ENABLE_WRITE_TOOLS=true

Tool Categories (28 read-only)

The groups are each handler's category, which ToolRegistry.getToolsByCategory() filters on.

• Security (2 tools): get_active_alarms, get_specific_alarm
• Network (7 tools): get_flow_data, get_bandwidth_usage, get_offline_devices, and the Wi-Fi controller tools get_access_points, get_access_point_channels, get_wifi_networks, get_wifi_settings
• Device (1 tool): get_device_status
• Rules (4 tools): get_network_rules, get_network_rules_summary, get_target_lists, get_specific_target_list
• Search (5 tools): search_flows, search_alarms, search_rules, search_devices, search_target_lists
• Analytics (9 tools): get_boxes, get_simple_statistics, get_statistics_by_region, get_statistics_by_box, get_recent_flow_activity, get_flow_insights, get_flow_trends, get_alarm_trends, get_rule_trends
• Convenience wrappers (client-side processing; counted in the groups above): get_bandwidth_usage, get_offline_devices, search_devices, search_target_lists, get_network_rules_summary
• Write tools (11, opt-in with FIREWALLA_ENABLE_WRITE_TOOLS=true): create_rule, delete_rule, pause_rule, resume_rule, create_target_list, update_target_list and delete_target_list (rules), rename_device (device), archive_alarm, mute_alarm and delete_alarm (security). Not counted in the 28. They need an MSP token with write access: MSP 2.12 adds read-only tokens, and a 403 on a write says the token may be read-only.