Firewalla MCP Server

Firewalla MCP服务器

](https://www.npmjs.com/package/firewalla-mcp-server)

一种模型上下文协议（MCP）服务器，通过28个专用工具提供对Firewalla防火墙数据的实时访问，与任何MCP客户端兼容。

为什么选择Firewalla MCP服务器？

简单的网络安全集成

• 28工具 用于网络监控和分析
• 23 API直接终点 + 5个便利包装
• 高级搜索 具有查询语法和过滤器
• 干净、经过验证的架构 具有已更正的API架构

特性

• 实时防火墙数据：查询安全警报、网络流量和设备状态
• 证券分析：了解威胁、被阻止的攻击和网络异常
• 带宽监控：跟踪顶级带宽消费者和使用模式
• 规则管理：查看并临时暂停防火墙规则
• 目标列表：管理自定义安全目标列表和类别
• 搜索工具：带过滤器和逻辑运算符的查询语法

客户端设置指南

运作原理

Claude Desktop/Code ↔ MCP Server ↔ Firewalla API

MCP服务器充当Claude和Firewalla防火墙之间的桥梁，将Claude的请求转换为Firewalla API调用，并以Claude能够理解的格式返回结果。

先决条件

• Node.js 18+和npm
• 具有API访问权限的Firewalla MSP帐户
• 您的Firewalla设备已联机并连接

快速开始

1.安装

选项A：从npm安装（推荐）

# Install globally
npm install -g firewalla-mcp-server

# Or install locally in your project
npm install firewalla-mcp-server

选项B：使用Docker

警告：不用于生产用途——流程列表中可见机密

下面的示例直接在命令行中传递凭据，这将它们暴露给进程列表和shell历史记录。对于生产使用，请考虑以下安全替代方案：

• 使用 --env-file 带着一个 .env 文件： docker run --env-file .env ...
• 在运行Docker之前，在shell中设置环境变量
• 在编排环境中使用Docker secrets

# Using Docker Hub image
docker run -it --rm \
  -e FIREWALLA_MSP_TOKEN=your_token \
  -e FIREWALLA_MSP_ID=yourdomain.firewalla.net \
  -e FIREWALLA_BOX_ID=your_box_gid \
  amittell/firewalla-mcp-server

# Or build locally
docker build -t firewalla-mcp-server .
docker run -it --rm \
  -e FIREWALLA_MSP_TOKEN=your_token \
  -e FIREWALLA_MSP_ID=yourdomain.firewalla.net \
  -e FIREWALLA_BOX_ID=your_box_gid \
  firewalla-mcp-server

# Recommended: Using env file (more secure)
docker run -it --rm --env-file .env amittell/firewalla-mcp-server

选项C：从源代码安装

git clone https://github.com/amittell/firewalla-mcp-server.git
cd firewalla-mcp-server
npm install
npm run build

2.配置

创建一个 .env 使用您的Firewalla凭据文件：

FIREWALLA_MSP_TOKEN=your_msp_access_token_here
FIREWALLA_MSP_ID=yourdomain.firewalla.net
FIREWALLA_BOX_ID=your_box_gid_here

获取您的凭据：

1. 登录您的Firewalla MSP门户网站 https://yourdomain.firewalla.net
2. 您的MSP ID是完整的域（例如。， company123.firewalla.net)
3. 在API设置中生成访问令牌
4. 在设备设置中查找您的Box GID（组ID）-这是您的唯一设备标识符

3.构建和启动

npm run build
npm run mcp:start

4.连接克劳德桌面

将此配置添加到您的Claude桌面 claude_desktop_config.json:

如果通过npm安装

{
  "mcpServers": {
    "firewalla": {
      "command": "npx",
      "args": ["firewalla-mcp-server"],
      "env": {
        "FIREWALLA_MSP_TOKEN": "your_msp_access_token_here",
        "FIREWALLA_MSP_ID": "yourdomain.firewalla.net",
        "FIREWALLA_BOX_ID": "your_box_gid_here"
      }
    }
  }
}

如果使用Docker

{
  "mcpServers": {
    "firewalla": {
      "command": "docker",
      "args": ["run", "-i", "--rm", 
        "-e", "FIREWALLA_MSP_TOKEN=your_token",
        "-e", "FIREWALLA_MSP_ID=yourdomain.firewalla.net",
        "-e", "FIREWALLA_BOX_ID=your_box_gid",
        "amittell/firewalla-mcp-server"
      ]
    }
  }
}

如果从源安装

{
  "mcpServers": {
    "firewalla": {
      "command": "node",
      "args": ["/full/path/to/firewalla-mcp-server/dist/server.js"],
      "env": {
        "FIREWALLA_MSP_TOKEN": "your_msp_access_token_here",
        "FIREWALLA_MSP_ID": "yourdomain.firewalla.net",
        "FIREWALLA_BOX_ID": "your_box_gid_here"
      }
    }
  }
}

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

5.下一步

• 看 用法.md 用于实际示例和常见查询
• 检查 故障排除.md 如果你遇到问题
• 查看中的客户特定设置指南 文档/客户端/

使用示例

第一步使用

1.验证连接 完成设置后，验证MCP服务器是否正常工作：

# Start the server
npm run mcp:start

# You should see output like:
# MCP Server starting...
# Firewalla client initialized
# Server ready on stdio transport

2.与克劳德一起测试 打开Claude Desktop并尝试以下入门查询：

基本健康检查：

"Can you check my Firewalla status and show me a summary?"

*这使用： firewall_summary 资源+ get_simple_statistics 工具*

安全概述：

"What security alerts do I have? Show me the 5 most recent ones."

*这使用： get_active_alarms 带限制参数的工具*

实用工作流程

每日安全审查：

"Give me today's security report. Include:
1. Any new security alerts
2. Top 3 devices using bandwidth
3. Any devices that went offline
4. Status of critical firewall rules"

调查可疑活动：

"I noticed unusual traffic. Can you:
1. Show me all security and abnormal upload alarms from the last 4 hours
2. Find any blocked connections to external IPs
3. Check which devices had the most network activity"

网络故障排除：

"A device seems to have connectivity issues. Can you:
1. Check if device 192.168.1.100 is online
2. Show its recent network flows
3. See if any rules are blocking its traffic"

带宽调查：

"Our internet is slow. Help me find the cause:
1. Show top 10 bandwidth users in the last hour
2. Look for any devices with unusual upload/download patterns
3. Check for any streaming or video traffic"

高级搜索示例

查找具体威胁：

search for: security activity alarms from IP range 10.0.0.* in the last 24 hours

*使用： search_alarms 使用查询：“类型：1，源代码：10.0.0。* 时间戳：>24h”\*

分析规则有效性：

"Show me firewall rules that blocked the most connections this week"

*使用： get_network_rules + search_flows 用于阻塞交通分析*

设备行为分析：

"Find all devices that were online yesterday but are offline now"

*使用： search_devices 使用时态查询+ get_offline_devices*

常见问题排查

连接问题： 如果您遇到身份验证错误：

1. 验证您的 .env 文件具有正确的凭据
2. 检查您的MSP令牌是否未过期
3. 确认您的Box ID是完整的GID格式

空结果： 如果查询未返回任何数据：

1. 检查您的Firewalla是否在线并报告
2. 验证时间范围是否太窄
3. 先尝试更广泛的搜索词

性能问题： 如果响应缓慢：

1. 减少查询中的限制参数
2. 使用更具体的时间范围
3. 检查您与MSP API的网络连接

可用工具（共28个）

核心工具

• 安全：获取警报，分析威胁
• 网络：监控流量，跟踪带宽使用情况
• 设备：检查设备状态，查找脱机设备
• 规则：管理防火墙规则、暂停/恢复规则
• 搜索：跨所有数据类型的高级搜索
• 分析：统计、趋势和地理分析
• 目标管理：创建、更新和删除安全目标列表

快速参考

Security: get_active_alarms, get_specific_alarm
Network: get_flow_data, get_bandwidth_usage, get_offline_devices  
Devices: get_device_status, get_boxes, search_devices
Rules: get_network_rules, pause_rule, resume_rule, get_target_lists
Search: search_flows, search_alarms, search_rules, search_target_lists
Analytics: get_simple_statistics, get_flow_insights, get_flow_trends, get_alarm_trends
Management: create_target_list, update_target_list, delete_target_list

发展

脚本

npm run dev          # Start development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run test         # Run all tests
npm run test:watch   # Run tests in watch mode
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues

MCP执行方法

为什么 npx 对于MCP服务器？

• 版本管理：始终使用正确/最新版本
• 依赖性解析：自动处理包依赖关系
• 无需全局安装：无需全局安装即可工作
• MCP标准：遵循模型上下文协议约定
• 可靠的：在不同环境中工作一致

替代执行方法：

# Development (from source)
npm run mcp:start

# Production (npm installed)
npx firewalla-mcp-server

# Direct execution (from source after build)
node dist/server.js

项目结构

firewalla-mcp-server/
├── src/
│   ├── server.ts           # Main MCP server
│   ├── firewalla/          # Firewalla API client
│   ├── tools/              # MCP tool implementations
│   ├── resources/          # MCP resource implementations
│   └── prompts/            # MCP prompt implementations
├── tests/                  # Test files
├── docs/
│   └── firewalla-api-reference.md  # API documentation
├── CLAUDE.md              # Comprehensive development guide
├── SPEC.md                # Technical specifications
└── README.md              # This file

文档

• README.md （此文件）-设置和基本用法
• 用法.md -带示例的简单使用指南
• 故障排除.md -常见问题和解决方案
• 文档/客户端/ -特定于客户端的设置指南
• CLAUDE.md -开发指南和命令

安全

• MSP令牌安全地存储在环境变量中
• 没有在代码中记录或存储凭据
• 利率限制防止API滥用
• 输入验证可防止注入攻击
• 所有API通信都使用HTTPS

已知行为和限制

类别分类

• 流量类别：许多网络流可能在Firewalla API响应中显示为空类别（“”）。这是预期的行为——Firewalla在识别域/服务时对流量进行分类（例如，音频/视频为“av”，社交媒体为“social”）。
• 目标列表类别：一些目标列表可能会将类别显示为“未知”。这对于用户创建的或某些系统列表来说是正常的。
• 时间线：类别分类发生在Firewalla设备级别，可能需要时间来建立有意义的分类数据。

数据特征

• 响应大小：The get_recent_flow_activity 该工具最多返回150个最近的流，以保持在令牌限制范围内。对于较大的数据集或历史分析，请使用 search_flows 使用时间过滤器进行更有针对性的查询。
• 地理数据：MCP服务器丰富了IP地理定位，包括国家、城市和风险评分（如果可用）。

API限制

• 报警删除：The delete_alarm 即使Firewalla API返回成功响应，该工具也可能不会实际删除警报。这似乎是MSP API的限制，其中删除操作返回 {"message": "success", "success": true} 但警报仍保留在系统中。这可能是由于权限限制或API设计。

故障排除

快速修复

服务器无法启动：

# Clean and rebuild
npm run clean
npm run build

# If build fails, try:
npm install
npm run build

身份验证错误：

• 检查您的MSP令牌是否有效
• 验证框ID格式（长UUID）
• 确认MSP域正确

未返回数据：

• 尝试更广泛的查询：“上周”vs“最后一小时”
• 检查Firewalla是否在线
• 测试：“向我展示基本统计数据”

响应缓慢：

• 添加限制：“前10名设备”
• 使用较短的时间范围
• 重新启动服务器

调试模式

启用详细日志记录：

DEBUG=mcp:* npm run mcp:start

有关更详细的故障排除，请参阅 故障排除.md

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 运行测试套件
6. 提交拉取请求

新增功能

版本1.0.0：

• 28个具有API验证架构的工具
• 24个直接API端点+5个方便包装器
• 新增：用于基于类别的流量分析的get_flow_insights
• 使用逻辑运算符（AND、OR、NOT）进行高级搜索
• 所有限值修正为API最大值（500）
• 为正确的API调用添加的必需参数
• 更好的缓存，更快的响应
• 处理高容量网络（300k+流量/天）

许可证

MIT许可证

支持

对于问题和疑问：

• 检查 故障排除指南
• 查看 技术规格
• 在GitHub上打开一个问题

______________________________________________________________________

GitHub存储库

仓库:

快速链接

• 问题
• 拉取请求
• 行动
• 安全

存储库统计信息

](https://github.com/amittell/firewalla-mcp-server/issues) ](https://github.com/amittell/firewalla-mcp-server/stargazers) ](https://github.com/amittell/firewalla-mcp-server/blob/main/LICENSE)