OPNsense MCP

用日常语言向你的防火墙提问。

四个用于 OPNsense 的只读工具——默认只读，并且对已验证的内容保持明确。

快速开始 · 工具 · 设置指南 · 证据 · 状态

预览： 一个小型 MCP 服务器，让 AI 助手检查 OPNsense 系统，并且——仅在明确启用时——在确认、备份和审计的包裹下创建或删除一种防火墙别名。它默认是只读的。打包的服务器同时针对合成 HTTPS 目标和一次性 OPNsense 26 虚拟机进行测试。

用日常语言提问。服务器会告诉代理从事实开始，解释网络术语，一次提出一个有用的澄清问题，并清楚地将观察与假设分开。

快速开始

只读，大约 15 分钟。需要 Node.js 22.19 或更高版本（在 22 主版本内），macOS 或 Linux。

1. 存储你的防火墙凭据

npx -y @gabrielion/opnsense-mcp configure

它会询问 HTTPS 源、API 密钥和机密，以及可选的 CA 文件。不会回显任何内容，也不会作为进程参数传递。需要先创建该密钥吗？设置指南 通过截图介绍了 OPNsense 侧的操作。

2. 连接你的助手

claude mcp add opnsense --transport stdio --env READ_ONLY=true -- npx -y @gabrielion/opnsense-mcp

[mcp_servers.opnsense]
command = "npx"
args = ["-y", "@gabrielion/opnsense-mcp"]

[mcp_servers.opnsense.env]
READ_ONLY = "true"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["npx", "-y", "@gabrielion/opnsense-mcp"],
      "environment": { "READ_ONLY": "true" }
    }
  }
}

3. 提问

我的 OPNsense 系统状态是什么？

我的防火墙上运行着哪些服务？

先运行 /mcp：服务器应显示 connected。添加它并不会验证凭据，因此 connected 才是真正的信号。

[!TIP] 手边没有防火墙，或者还没准备好将其指向你的防火墙？ npm run test:product1b 会启动一个一次性 OPNsense 虚拟机，创建自己的最小权限账户（不涉及你的任何凭据），针对它验证整个读取面，然后清理。

Related MCP server: OPNsense MCP Server

目前可用的功能

默认情况下，安装的服务器暴露四个只读工具：

• server_status 检查 MCP 进程及其只读状态。

• opn_describe 在代理使用可见资源之前解释该资源。

• opn_get 读取单例资源 system.status。

• opn_list 分页列出集合资源 core.services 和 firewall.alias。对于别名，它仅列出主机条目，报告的总数也仅统计这些；其他别名类型不显示。

还始终注册了三个 MCP 提示——diagnose_network_problem、publish_internal_service 和 block_domain_for_device。它们只生成只读的准备计划；不执行任何操作。

READ_ONLY=true 是默认值，在此模式下，没有写入工具被列出或可调度。

存在两个实验性写入工具 opn_create 和 opn_delete，它们仅操作 firewall.alias 的主机条目。三个条件加上受支持的传输方式决定它们是否被列出：

• READ_ONLY=false；

• ENABLED_FEATURE_FLAGS 包含 experimental-alias-write；

• ALLOWED_RESOURCES 明确命名 firewall.alias。缺失或空的允许列表授权所有读取，且不授权任何写入。允许列表也会过滤读取，因此请列出你仍然需要的每个范围，例如 ALLOWED_RESOURCES=server.status,system.status,core.services,firewall.alias；

• 传输方式是 stdio 或 Streamable HTTP。旧版 SSE 从不列出或调度它们。

第四个条件管理调用而非列出：客户端必须已协商表单引导。没有该能力的客户端仍会看到工具，但在任何挑战或写入之前，每次尝试都会以 CONFIRMATION_UNAVAILABLE 被拒绝。

每次写入都按此固定顺序执行此固定包裹：授权、命名变更的人工确认、对目标的独占锁、无副作用的预检、脱敏的审计意图、已验证的变更前备份、重新检查观察到的状态未移动、写入、结果验证、最终审计记录以及锁释放。备份后的每次失败都会保留备份，且绝不盲目恢复。

这些写入之所以是实验性的，是有原因的。 变更前备份写入每个进程的临时目录，该目录在服务器关闭时被删除，因此之后无法查阅。审计是内存中的环形缓冲区，仅保留最近 1024 条记录（每次写入两条），没有持久化形式，也没有读取它的工具。锁是进程本地的，因此指向同一防火墙的两个服务器不会互相排斥。

包裹所保证的内容虽窄但真实：除非先记录已验证的备份和审计意图，否则拒绝写入。没有恢复，也没有回滚——如果在应用变更后发生失败，变更保持应用状态，恢复需通过 OPNsense 自身的配置历史手动进行。使此状态持久化是下一个里程碑。

快速本地验证

要求：Node.js 22.19 或更高版本（在 22 主版本内）、npm、macOS 或 Linux。

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
npm ci --ignore-scripts &&
npm run test:product1a &&
npm run build

npm run test:product1a 创建一个干净的 npm tarball，将其安装到隔离的消费者项目中，连接到单独拥有的合成 HTTPS OPNsense 目标，通过原始 MCP stdio 调用所有三个 OPNsense 工具，检查机密从未出现，在 EOF 时关闭，并移除所有夹具。

连接你的 OPNsense 实例

支持提供凭据的方式是交互式命令，它会以正确的所有权和模式为你写入私有文件。从克隆中，它是构建入口点的子命令：

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
node dist/main.js configure

从注册表安装后，同一子命令是 npx -y @gabrielion/opnsense-mcp configure。

它会提示输入 HTTPS 源、API 密钥、API 机密以及可选的 CA 文件和 TLS 服务器名称；机密永远不会回显，也永远不会出现在进程参数中。它拒绝在 Windows 上运行，并拒绝任何参数。

它始终写入平台路径，并忽略 OPNSENSE_CONFIG_FILE，后者是服务器端变量：

• macOS：~/Library/Application Support/opnsense-mcp/config.json；

• Linux：$XDG_CONFIG_HOME/opnsense-mcp/config.json，否则为 ~/.config/opnsense-mcp/config.json。

服务器发现相同的路径，因此该变量仅在需要读取存储在其他位置的文件时才需要。它拥有的每个目录都以模式 0700 创建，文件以模式 0600 创建；拒绝符号链接、外部所有者和不安全的祖先。

两个实际限制：它从不覆盖现有配置，因此轮换密钥需先删除文件；并且它要求两个流都是真实终端，因此无法通过管道或 CI 运行。每次失败都故意打印单词 Error——诊断故意不透明，以免泄露私有路径或凭据。

或者，在仓库外部自行创建 JSON 文件，并用模式 0600 保护：

{
  "url": "https://192.0.2.1",
  "apiKey": "your-dedicated-read-only-api-key",
  "apiSecret": "your-api-secret",
  "caFile": "/absolute/path/to/your-ca.pem",
  "tlsServerName": "firewall.example.internal"
}

该文件必须是当前用户拥有的常规非符号链接文件，位于绝对路径，模式恰好为 0600，恰好一个硬链接，且最大 16 KiB。0400 也被拒绝。url 必须是一个精确的 HTTPS 源。当防火墙证书已链接到受信任的 CA 时，caFile 是可选的。当 URL 使用 IP 地址但已验证的证书使用 DNS 名称时，tlsServerName 是可选的。TLS 验证始终启用。使用专用的最小权限 OPNsense 密钥；不要将凭据粘贴到聊天或命令参数中。

传输方式。 stdio 是默认值，也是打包证明端到端演练的唯一传输方式；dist/main.js 始终启动 stdio。存在一个 Streamable HTTP 传输作为单独的入口点（npm run start:http），位于 MCP_HTTP_ENABLED 之后，绑定到回环，带有 Host/Origin 允许列表和至少 32 个字符的 bearer MCP_HTTP_TOKEN；它没有客户端冒烟测试覆盖，因此不对其做出客户端支持声明。存在一个旧版 SSE 兼容表面，位于 MCP_LEGACY_SSE_ENABLED 之后，它额外要求 MCP_HTTP_ENABLED=true——单独设置它是启动错误——并且从不暴露基于确认的写入工具。

要直接运行协议干净的 stdio 服务器：

if test -x /opt/homebrew/opt/node@22/bin/node; then
  export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
fi
node -e "const [major, minor] = process.versions.node.split('.').map(Number); process.exit(major === 22 && minor >= 19 ? 0 : 1)" &&
OPNSENSE_CONFIG_FILE="/absolute/path/to/opnsense.json" READ_ONLY=true node dist/main.js

切勿将开发或测试指向生产防火墙。对于实际工作，请使用下面的一次性虚拟机证明。

一次性 OPNsense 26 证明

在 macOS 或 Linux 上，安装 QEMU 和 Node.js 22，然后运行：

npm run vm:doctor
npm run test:product1b

vm:doctor 报告每个缺失的主机依赖项而不更改机器。test:product1b 拥有整个实时测试：它验证并缓存固定的官方 OPNsense 26.7 nano 镜像，启动一个本地虚拟机，通过串行控制台创建一次性最小权限 API 用户（无需任何操作员凭据），打包并安装此 npm 包，通过一个 MCP 会话调用 server_status、opn_describe system.status、opn_get system.status 和 opn_list core.services，然后停止虚拟机并移除覆盖层、API 凭据、证书和临时包。首次运行会下载约 557 MB 的存档，并在用户缓存中创建 3 GiB 的只读基础镜像。

历史 Product 1B 证据仅作为两个远程调用的证明：GET /api/core/system/status 和 POST /api/core/service/search。其经过清理的机器可读证据还记录了其确切的主机、QEMU、固件、传输和清理检查，而不保留防火墙数据或凭据。

别名写入实现针对 GET /api/core/backup/download/this 进行变更前备份，然后 POST /api/firewall/alias/searchItem、addItem 或 delItem/{uuid}，然后 reconfigure 应用。这些端点细节具有确定性的合成目标覆盖。Product 3 在一次性虚拟机上仅证明以下内容：可写表面和这个确切的 firewall.alias 生命周期：不存在、创建、存在、删除、不存在，然后是虚拟机清理和无残留检查。提交绑定的 Product 3 虚拟机证明记录了测试的提交和树、固定的固件镜像、策略输入和固定的生命周期检查，而不保留防火墙数据或凭据。Product 3 证明不证明生产使用、持久状态、持久备份、持久审计跟踪、恢复或自动回滚。

恢复往返还直接通过一次性虚拟机的控制台——而非 API——恢复相同的别名变更，然后重新观察 API 以检查变更已消失。恢复往返 Product 3 虚拟机证明记录了测试的提交和树、相同的固定固件镜像和策略输入、别名生命周期检查以及备份恢复和状态还原检查，同样不保留防火墙数据或凭据，使用 node scripts/vm/product3-restore.mjs --attestation-out "$PWD/docs/evidence/product3-restore-vm.json" 生成。

一次性账户权限。 这些账户仅使用这些标准 ACL 创建，不附加任何其他权限。两个 ACL 配置文件现在都只在其确切场景中具有实时证据：只读配置文件在 Product 1B 中，别名写入配置文件在 Product 3 中。

• 只读账户：page-system-status、page-status-services、user-config-readonly；

• 别名写入账户：page-system-status、page-status-services、 page-diagnostics-configurationhistory、page-firewall-alias-edit。

user-config-readonly 被有意排除在别名写入账户之外：我们观察到它会导致 OPNsense 可变模型控制器拒绝别名保存。page-diagnostics-configurationhistory 是为变更前配置备份请求授予的。这两项陈述均来自我们自己的引导经验，而非引用的上游映射。

OpenCode

添加一个项目级 opencode.json（替换两个绝对路径）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opnsense": {
      "type": "local",
      "command": ["node", "/absolute/path/to/OPNSenseMCP/dist/main.js"],
      "environment": {
        "READ_ONLY": "true",
        "OPNSENSE_CONFIG_FILE": "/absolute/path/to/opnsense.json"
      }
    }
  }
}

然后运行 opencode mcp list；opnsense 应显示为已连接。已提交的冒烟证据仅涵盖 OpenCode 1.18.16 配合 opencode/deepseek-v4-flash-free 针对已安装的 tarball 和合成 HTTPS 目标。它记录的是工具/结果摘要，而非防火墙数据或凭据。请参阅 机器可读证据。

其他 MCP 客户端可以启动相同的 stdio 命令，但在其自身版本化的冒烟测试通过之前，不做出任何特定于客户端的支持声明。

此预览版如何测试

• 严格的 TypeScript、格式化、lint、许可证头，以及确定性的单元/集成测试。

• 干净的 npm pack/install，外加针对合成目标的 TLS、Basic 认证、响应验证、机密信息脱敏、关闭和清理。

• 针对一次性 OPNsense 26.1.6 虚拟机的历史性干净 npm pack/install，用于两次 Product 1B 远程调用，包括虚拟机所有权、固定镜像完整性、隔离凭据、TLS 固定和反向清理。

• 针对一次性 OPNsense 26.7 虚拟机的提交绑定 Product 3 运行，覆盖可写表面和精确的主机别名生命周期：不存在、创建、存在、删除、不存在，随后进行虚拟机清理和无残留检查。

• 针对合成目标证明以及两个虚拟机运行器的封闭式包安装：消费者从基于锁文件的仅回环 npm 注册表中解析每个依赖项，缓存为空且代理不可达，因此不涉及任何互联网访问，也没有上游版本可以更改已安装的内容。

• 针对协议版本 2025-11-25 和草案 2026-07-28 的定向 MCP 互操作性检查。

• 一次使用 opencode/deepseek-v4-flash-free 的真实 OpenCode 1.18.16 路由冒烟测试。

完整的开发状态和机器对机器交接记录在 docs/project-status.md 中。计划中的规范智能体评估在 DeepEval 和 OPNsense 评估设计 中指定： 它将评估 Claude Code 的 MCP 工具使用和最终响应，同时单独要求对一次性虚拟机状态进行确定性 MCP 回读。这些测试和任何基准分数尚未实现或声明。

这些检查共同覆盖了包、合成读取路径、两次已声明的历史 Product 1B 远程调用，以及上述有界生命周期，仅此而已。它们不证明：

• 在互联网上暴露公共 DNS、ACME 或 HAProxy；

• 针对生产防火墙的行为；

• 持久备份或持久审计跟踪：两者都存在，但仅存在于进程生命周期内；

• 恢复，或对已应用更改的任何自动回滚；

• 写入 firewall.alias 主机条目以外的任何内容；

• 超出前 100 个主机别名的任何保证：变更前状态摘要和回读都只读取一页 100 条，因此超过该数量后，创建可能报告未验证的结果，而删除只能证明该条目不在其读取的页面上；

• 原生 Windows 安装或客户端操作；

• 完整的智能体基准或基准分数。

原始 API 分发、自由形式的 shell/SSH、批量 IaC、仪表板以及广泛的传统功能对等均不存在。

产品路线图和示例请求

变更安全边界——范围化授权、人工确认、已验证备份、脱敏审计、结果验证、故障关闭清理——已实现并针对合成 HTTPS 目标得到证明。下一个 里程碑是使其状态持久化：持久状态根、进程间锁、仅追加审计，以及本地 reconcile 命令，以便这些保证在重启后仍然有效。只有到那时，才能重新考虑别名写入上的 experimental 标签。

后续的引导式工作流有意设定为用户级目标，例如：

• “我的笔记本电脑每天晚上都会断网。你能调查并解释你的发现吗？”

• “仅阻止我孩子平板上的 TikTok，而不影响其他设备。”

• “使用友好的 DNS 名称、内部证书和反向代理在内部发布此服务。”

这三个工作流是路线图示例，而非 Product 1A 声明。面向互联网的发布（使用公共 DNS、Let's Encrypt 和 HAProxy）是在安全写入和私有虚拟机覆盖之后的一个长期实验室里程碑。

分发状态： 已作为 @gabrielion/opnsense-mcp 发布到 npm，因此 npx -y @gabrielion/opnsense-mcp 会运行已发布的服务器；git URL 安装仍会通过 prepare 脚本构建自己的 dist/。打包的证明无论哪种方式都安装由基于锁文件的回环注册表提供的本地构建 tarball，因此它们所验证的是此树，而非任何注册表副本。目前不提供任何版本控制或升级保证。

平台状态： macOS 和 Linux 是当前已验证的开发主机。原生 Windows 仍然是必需的产品目标，但在后续的 windows-2025 门禁通过之前，不声明包和客户端支持。

许可证和商标

根据 AGPL-3.0-or-later 许可；请参阅 LICENSE。AGPL 允许商业使用，同时要求提供所涵盖的源代码，包括网络使用。OPNsense 是 Deciso B.V. 的商标。此独立项目与 Deciso B.V. 或 OPNsense 项目无关联、未获其赞助，也未获其认可。