用途
OPNSenseMCP 是用于 OPNsense 开源防火墙的 Model Context Protocol（MCP）服务器，定位为基础设施即代码（IaC）代理。其核心用途是让 Claude 等 AI 助手通过自然语言直接管理 OPNsense 防火墙，完成配置变更、网络诊断与自动化任务，减少手动操作和命令行交互成本。
主要能力
- 防火墙管理：防火墙规则的完整 CRUD 操作、正确处理 API 创建的“自动化规则”、VLAN 间路由配置、批量规则创建与管理、通过多种回退方式增强持久性。
- NAT 配置（基于 SSH）：出站 NAT 规则管理、NAT 模式控制（自动/混合/手动/禁用）、VLAN 间流量的 No-NAT 例外规则、DMZ NAT 问题自动修复、直接 XML 配置操作。
- 网络诊断：全面的路由分析、带厂商识别的 ARP 表检查、接口配置管理、网络连通性故障排除、常见问题自动修复。
- SSH/CLI 执行：在 OPNsense 上直接执行命令、配置文件操作、通过 API 不可用的系统级操作、服务管理与重启。
- 附加能力：VLAN 管理、DHCP 租约查看与管理、DNS 阻止列表配置、HAProxy 负载均衡支持、配置备份与恢复、基础设施即代码支持。
使用方式
运行环境要求 Node.js 18+（开发需 Bun 1.1.39+），需要 OPNsense 防火墙（推荐 v24.7+）、API 凭据，SSH 访问为可选（用于高级功能）。
通过 npm 快速开始：安装包、创建包含凭据的 .env 文件、启动 MCP 服务器。也可使用 Bun 以获得更快的启动和更好的性能：安装 Bun、克隆并安装、创建 .env 文件。
在 Claude Desktop 中使用 npm 版本时，需将服务器配置添加到 claude_desktop_config.json。
安全模式
默认情况下，该服务器可对防火墙进行实时、即时更改，包括增删规则、更改 NAT、重启服务、通过 SSH 运行白名单 shell 命令。服务器提供两个仅限操作员设置的环境变量作为安全网，工具调用无法设置或覆盖它们；两者在 API 客户端与 SSH 执行器两个底层节点统一强制执行，覆盖全部 140 多个工具。若两者同时设置，OPNSENSE_READ_ONLY 优先。具体配置可参考 CONFIGURATION.md，工作原理可参考 docs/features/safety-modes.md。
MCP 工具
服务器提供 50+ 个按类别组织的 MCP 工具，例如：firewall_list_rules、firewall_create_rule、firewall_update_rule、firewall_delete_rule、firewall_apply_changes、nat_list_outbound、nat_set_mode、nat_create_outbound_rule、nat_fix_dmz、nat_analyze_config、arp_list、routing_diagnostics、routing_fix_all、interface_list、vlan_create、system_execute_command、backup_create、service_restart。完整列表见 docs/api/mcp-tools.md。
构建与项目结构
该项目开发使用 Bun 作为工具链，但发布包仍为普通 Node，通过 node dist/index.js 使用，因此 Bun 仅用于参与项目开发。锁文件为 bun.lock，没有 package-lock.json，CI 运行 bun install --frozen-lockfile，因此 package.json 变更时需一并提交 bun.lock。
常见问题排查
- API 认证失败：验证 API 密钥与密钥正确；确保 OPNsense 中启用了 API 访问；检查防火墙规则允许 API 访问。
- SSH 连接失败：验证 .env 中的 SSH 凭据；确保 OPNsense 上启用了 SSH；检查用户是否具有适当权限。
- NAT 功能不工作：NAT 管理需要 SSH 访问；在环境变量中添加 SSH 凭据；可使用 npx tsx scripts/test/test-nat-ssh.ts 测试。
限制与状态
NAT 配置及相关功能依赖 SSH 访问；部分系统级操作无法通过 API 完成。项目采用 MIT 许可证，版本 0.8.2，状态为生产就绪，最后更新于 2025 年 8 月。详细文档、快速入门、配置指南、SSH/CLI 执行说明、故障排除及完整 API 参考可在仓库文档中查阅。