firewalla-mcp-server

一个只读的 Model Context Protocol (MCP) 服务器，让 Claude 可以通过 Firewalla MSP API 审计您的 Firewalla 配置和网络安全态势。

设计为只读。 此服务器无法阻止/解除阻止设备、创建或修改规则、暂停服务或对您的 Firewalla 进行任何更改。它仅用于观察。

功能介绍

提供了 8 个工具，Claude 可以使用这些工具来检查您的 Firewalla — 包括网络上的设备、活动规则、安全警报、网络流以及阻止/允许目标列表。

提示词示例

安全审计

这些提示词将 Claude 视为一名网络安全专家，对您的 Firewalla 配置进行结构化审查。它们在 Claude Desktop 或 Claude Code 中效果最佳，因为这些环境可以使用 Firewalla MCP 工具。

全网安全审计：

你是一位高级网络安全工程师，正在对我的家庭网络进行全面审计。使用 Firewalla MCP 工具，执行以下审查并以结构化报告的形式呈现你的发现，并附上严重性评级（严重 / 高 / 中 / 低 / 信息）：

1. 设备清单 — 拉取完整的设备列表。标记任何具有无法识别的 MAC 厂商的设备、未被监控的设备，或可能表明存在非法接入点的意外路由器类设备。

2. 规则审计 — 审查所有阻止/允许规则。识别任何过于宽松的允许规则（范围过广、入站方向、无设备限制）。标记命中次数为零且可能已过期的规则。

3. 警报审查 — 按类型和严重性对最近的警报进行分组搜索。识别任何模式（来自同一设备的重复警报、来自意外国家的警报、针对不应有外部暴露的设备的警报）。

4. 目标列表覆盖范围 — 审查哪些阻止列表处于活动状态。评估当前的列表配置是否针对常见的威胁类别（恶意软件、C2、网络钓鱼、加密货币挖矿、新注册域名）提供了足够的覆盖范围。

最后，列出一份我应该采取的优先行动清单，以改善我的网络安全态势。

防火墙规则差距分析：

扮演防火墙策略分析师的角色。拉取我所有的 Firewalla 规则和完整的设备列表，然后进行交叉引用。我需要你识别：(1) 完全没有任何规则作用于其上的设备 — 它们是否完全依赖全局规则，这是否是有意的？(2) 授予入站访问权限的允许规则 — 它们针对哪些设备，范围是否足够窄？(3) 从未触发过的阻止规则（命中次数 = 0） — 它们是过期的，还是它们所防范的威胁根本不存在？请以表格形式为每个类别呈现你的发现，并附上你的评估和建议行动。

可疑流量调查：

我想调查我的网络上是否有任何设备正在与意外的外部目的地通信。搜索我最近的网络流，查找任何未被 Firewalla 阻止的流向美国以外地区的流量。按设备和目的地国家/地区对结果进行分组。对于任何显示有未被阻止的流向异常地区流量的设备，将其与我的设备列表进行交叉引用以识别该设备是什么，然后检查是否有任何与之相关的警报。总结你的发现，并为每个被标记的设备提供风险评估。

快速查询

这些是用于日常监控和抽查的简短提示词：

• “列出我网络上的所有设备，并标记任何具有未知 MAC 厂商或未被 Firewalla 监控的设备。”

• “向我展示我 Firewalla 上的所有允许规则。它们中是否有范围太广的？”

• “目前我网络上触发最多的警报类型是什么？按类型分组并给出计数。”

• “检查我激活了哪些 Firewalla 阻止列表，以及每个列表有多少条目。我是否遗漏了任何重要的类别？”

• “搜索过去 24 小时内任何被阻止的流量，并按目的地国家/地区进行分组。哪些国家/地区出现的频率最高？”

• “拉取我的 Firewalla 盒子信息 — 它是否在线，运行的是什么固件版本，目前有多少活动警报？”

工具

所有工具都支持 response_format: "json" | "markdown" 并且被标注为 readOnlyHint: true。

先决条件

1. 一个 Firewalla 盒子，链接到 MSP 账户。即使是独立（非集群）盒子也使用 MSP API — 这是唯一支持的公共 API。

2. 一个 MSP 个人访问令牌。 在以下位置生成一个：

   • 登录您的 MSP 门户 https://<your-subdomain>.firewalla.net

   • 转到 Account Settings → Personal Access Tokens

   • 创建一个新令牌并将其保存在安全的地方

   有关详细的设置说明，请参阅 Getting Started with the Firewalla MSP API。

3. Node.js 18+

安装

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

配置

服务器读取两个环境变量：

对于本地开发，将 .env.example 复制到 .env 并填入您的值：

cp .env.example .env
# edit .env with your real values

与 Claude Desktop 一起使用

添加到您的 claude_desktop_config.json（在 macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "firewalla": {
      "command": "node",
      "args": ["/absolute/path/to/firewalla-mcp/dist/index.js"],
      "env": {
        "FIREWALLA_MSP_DOMAIN": "yourname.firewalla.net",
        "FIREWALLA_MSP_TOKEN": "your-token-here"
      }
    }
  }
}

注意： Claude Desktop 启动时使用最小化的 PATH。如果找不到 node，请使用 Node.js 二进制文件的绝对路径（例如 which node 的输出）。

编辑配置后重启 Claude Desktop。

与 Claude Code 一起使用

claude mcp add-json --scope user firewalla '{
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/firewalla-mcp/dist/index.js"],
  "env": {
    "FIREWALLA_MSP_DOMAIN": "yourname.firewalla.net",
    "FIREWALLA_MSP_TOKEN": "your-token-here"
  }
}'

验证：

claude mcp list
# firewalla: ... - ✓ Connected

新的 Claude Code 会话将自动拥有 firewalla_* 工具。

开发

# Source env for local dev
set -a; source .env; set +a

# Run with auto-reload
npm run dev

# Build
npm run build

# Test with MCP Inspector
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

Firewalla API 文档

• Firewalla MSP API 参考

• MSP API 示例 (GitHub)

• MSP API 入门

许可证

MIT