OPNsense MCP Server
OPNsense MCP 服务器
一个安全的模型上下文协议(MCP)服务器,用于通过 AI 助手(如 Claude Code、Cursor 及其他兼容 MCP 的工具)管理 OPNsense 防火墙。
81 个工具,覆盖 10 个领域:系统、防火墙、网络、DNS、DHCP、VPN、HAProxy、服务、诊断和安全。
要求
Python 3.11+
OPNsense 24.7 或更新版本 — MCP 服务器依赖 OPNsense 24.7 中引入的基于 MVC 的 API 端点。旧版本使用不同的 API 结构,不兼容。服务器在首次连接时自动检测 OPNsense 版本,并选择正确的端点命名方式(25.7 之前为 camelCase,25.7+ 为 snake_case)。OPNsense 26.x 完全受支持,包括其更改后的固件状态响应格式。
Related MCP server: OPNsense MCP Server
安全模型
该 MCP 服务器以安全为首要设计目标:
默认只读 — 写操作需要通过
OPNSENSE_ALLOW_WRITES=true显式启用保存点/回滚(仅限 OPNsense < 26.7) — 在 OPNsense 仍提供保存点 API 的情况下,防火墙修改使用其内置的 60 秒自动还原机制;更改必须被明确确认,否则会自动回滚。OPNsense 26.7 上游移除了该 API — 服务器在运行时检测缺失的端点,并立即应用防火墙更改,无自动回滚
端点阻止列表 — 危险端点(
halt、reboot、poweroff、firmware update/upgrade)在 API 客户端层面被硬性阻止,永远无法被调用仅 API — 无 SSH 访问、无命令执行、无直接配置文件操作
本地传输 — 仅 STDIO,无网络暴露的 HTTP/SSE 端点
不暴露凭据 — API 密钥永远不会出现在工具输出、日志或错误消息中
输入验证 — 主机名参数针对 shell 元字符注入进行验证
敏感数据剥离 — 配置备份默认剥离密码和密钥
快速开始
1. 创建 OPNsense API 密钥
登录您的 OPNsense Web 界面
前往 系统 > 访问 > 用户
编辑现有用户或创建专用 API 用户:
对于生产环境,创建一个专用用户(例如
mcp-api),仅授予所需权限对于只读访问,将该用户分配到具有只读 API 访问权限的组
向下滚动到 API 密钥 部分,点击 + 按钮
将生成一对密钥/机密,并下载一个文件(
apikey.txt)该文件包含两行 —
key=your-api-key-here和secret=your-api-secret-here安全存储这些凭据 — 机密无法再次从 OPNsense 中检索
提示: 对于只读设置(建议入门使用),你无需更改任何权限 — 默认 API 访问足以使用所有只读工具。
2. 安装
# Using pip
pip install opnsense-mcp-server
# Using uv (recommended for isolated environments)
uv pip install opnsense-mcp-server
# Using Docker
docker pull uhlenheide/opnsense-mcp-server
# From source
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e .Docker 镜像: 官方镜像是
uhlenheide/opnsense-mcp-server,由.github/workflows/publish-docker.yml在每个v*标签上从本仓库发布。不存在lucamarien/opnsense-mcp-server镜像 — 早期 README 版本误用了该名称。
3. 配置你的 AI 助手
Claude Code
添加到你的项目 .mcp.json:
{
"mcpServers": {
"opnsense": {
"command": "opnsense-mcp",
"env": {
"OPNSENSE_URL": "https://192.168.1.1/api",
"OPNSENSE_API_KEY": "your-api-key-here",
"OPNSENSE_API_SECRET": "your-api-secret-here",
"OPNSENSE_VERIFY_SSL": "false",
"OPNSENSE_ALLOW_WRITES": "false"
}
}
}
}替代方案: 如果
opnsense-mcpCLI 不在你的 PATH 中,可使用"command": "python", "args": ["-m", "opnsense_mcp"]。
或者全局添加到 ~/.claude/claude_code_config.json。
Claude Code(Docker)
{
"mcpServers": {
"opnsense": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "OPNSENSE_URL=https://192.168.1.1/api",
"-e", "OPNSENSE_API_KEY=your-api-key-here",
"-e", "OPNSENSE_API_SECRET=your-api-secret-here",
"-e", "OPNSENSE_VERIFY_SSL=false",
"-e", "OPNSENSE_ALLOW_WRITES=false",
"uhlenheide/opnsense-mcp-server"
]
}
}
}Cursor
添加到你的 Cursor MCP 设置(设置 > MCP):
{
"mcpServers": {
"opnsense": {
"command": "opnsense-mcp",
"env": {
"OPNSENSE_URL": "https://192.168.1.1/api",
"OPNSENSE_API_KEY": "your-api-key-here",
"OPNSENSE_API_SECRET": "your-api-secret-here",
"OPNSENSE_VERIFY_SSL": "false"
}
}
}
}配置
环境变量 | 默认值 | 描述 |
| (必填) | OPNsense API 基础 URL(必须以 |
| (必填) | 来自 OPNsense 用户设置的 API 密钥 |
| (必填) | 来自 OPNsense 用户设置的 API 机密 |
|
| 验证 SSL 证书(自签名证书使用 |
|
| 启用写操作(防火墙规则、服务控制) |
自定义端口: 如果你的 OPNsense Web GUI 运行在非标准端口(例如 10443),请在 URL 中包含它:https://192.168.1.1:10443/api
可用工具(81 个)
系统(7 个工具)
工具 | 描述 |
| 系统信息,包括固件版本、产品名称和架构 |
| 列出所有服务及其运行状态。参数: |
| 网关可用性、延迟和 dpinger 健康检查 |
| 下载 |
| 扫描完整配置,将其解析为各节,并收集运行时清单(固件、插件、DHCP、DNS、接口、服务)。结果按会话缓存。参数: |
| 获取特定配置节作为结构化 JSON。参数: |
| MCP 服务器版本、写模式状态、检测到的 OPNsense 版本、API 风格,以及防火墙写入是否仍受保存点/回滚保护 |
网络(5 个工具)
工具 | 描述 |
| 每个接口的流量统计(字节入/出、数据包、错误) |
| ARP 表,显示 IP 到 MAC 地址的映射 |
| NDP(邻居发现协议)表,显示 IPv6 到 MAC 地址的映射 |
| 所有接口的 IPv6 配置和地址状态(方法、实时地址、摘要) |
| 已配置的静态路由。参数: |
防火墙(21 个工具)
工具 | 描述 | 写入 |
| 列出 MVC 防火墙过滤规则。参数: | 否 |
| 列出别名定义(IP 列表、端口组、GeoIP、URL)。参数: | 否 |
| 列出 NAT 端口转发(DNAT)规则。参数: | 否 |
| 列出防火墙规则类别及其 UUID。参数: | 否 |
| 最近的防火墙日志条目,支持客户端过滤。参数: | 否 |
| 确认待定的更改,取消 60 秒自动回滚(OPNsense < 26.7;在 26.7+ 上为无操作,返回 | 是 |
| 使用保存点切换规则的启用/禁用状态(OPNsense < 26.7)。参数: | 是 |
| 使用保存点创建新的过滤规则(OPNsense < 26.7)。参数: | 是 |
| 使用保存点按 UUID 删除过滤规则(OPNsense < 26.7)。参数: | 是 |
| 创建新的别名。参数: | 是 |
| 使用保存点创建 NAT 端口转发规则(OPNsense < 26.7)。参数: | 是 |
| 创建新的防火墙规则类别。参数: | 是 |
| 使用保存点按 UUID 删除防火墙规则类别(OPNsense < 26.7)。参数: | 是 |
| 使用保存点为防火墙规则分配类别(OPNsense < 26.7)。参数: | 是 |
| 根据 RFC 4890 创建 IPv6 运行所需的必要 ICMPv6 规则(NDP、RA、ping6)。参数: | 是 |
| 更新现有别名(name、content、type、description)。读-改-写。参数: | 是 |
| 按 UUID 删除别名。先检查规则引用。参数: | 是 |
| 切换别名的启用/禁用状态。参数: | 是 |
| 使用保存点更新过滤规则字段(OPNsense < 26.7)。参数: | 是 |
| 使用保存点更新 NAT 端口转发规则(OPNsense < 26.7)。参数: | 是 |
| 使用保存点按 UUID 删除 NAT 端口转发规则(OPNsense < 26.7)。参数: | 是 |
注意: 保存点保护仅存在于 OPNsense < 26.7。在 26.7+ 上,这些工具会立即且永久地应用更改——请参阅写入操作与保存点。
DNS(13 个工具)
工具 | 描述 | 写入 |
| Unbound 主机覆盖(本地 DNS 记录)。参数: | 否 |
| DNS 转发域(特定域服务器)。参数: | 否 |
| Unbound 解析器统计(查询、缓存命中、运行时间) | 否 |
| 应用待定的 DNS 解析器配置更改 | 是 |
| 添加 Unbound DNS 主机覆盖(A/AAAA 记录)并立即应用。参数: | 是 |
| 列出 DNSBL 黑名单配置,包含提供商和状态。参数: | 否 |
| 按 UUID 获取完整的 DNSBL 配置(提供商、允许列表、设置)。参数: | 否 |
| 更新 DNSBL 设置(读-改-写)。参数: | 是 |
| 将域名添加到 DNSBL 允许列表而不覆盖。参数: | 是 |
| 从 DNSBL 允许列表中移除域名。参数: | 是 |
| 重新加载 DNSBL 黑名单文件并重启 Unbound(无配置更改,恢复工具) | 是 |
| 更新 Unbound DNS 主机覆盖并立即应用。参数: | 是 |
| 删除 Unbound DNS 主机覆盖并立即应用。参数: | 是 |
DHCP(8 个工具)
工具 | 描述 | 写入 |
| 来自 ISC DHCP 服务器的活动 DHCPv4 租约 | 否 |
| 来自 Kea DHCP 服务器的 DHCPv4 租约。参数: | 否 |
| 来自 dnsmasq DNS/DHCP 服务器的 DHCPv4 和 DHCPv6 租约。参数: | 否 |
| 已配置的 DHCP 地址范围(包括带 RA 配置的 DHCPv4 和 DHCPv6)。参数: | 否 |
| 创建新的 DHCP 范围(IPv4 或带路由器通告配置的 IPv6)。参数: | 是 |
| 应用待处理的 dnsmasq DNS/DHCP 配置更改 | 是 |
| 更新 DHCP 范围(地址、租约时间、RA 配置)并应用。参数: | 是 |
| 按 UUID 删除 DHCP 范围并应用。参数: | 是 |
VPN(3 个工具)
工具 | 描述 |
| WireGuard 隧道和对等体状态(需要 os-wireguard 插件) |
| IPsec VPN 隧道状态 — IKE(阶段 1)和 ESP/AH(阶段 2)会话 |
| OpenVPN 连接状态 — 实例、会话和路由 |
HAProxy(8 个工具)
HAProxy 负载均衡器的完整配置管理(需要 os-haproxy 插件)。
工具 | 描述 | 写入 |
| HAProxy 服务状态和后端健康检查 | 否 |
| 按类型搜索 HAProxy 资源。参数: | 否 |
| 获取特定资源的详细配置。参数: | 否 |
| 在应用前验证 HAProxy 配置语法 | 否 |
| 创建新的 HAProxy 资源。参数: | 是 |
| 更新现有 HAProxy 资源(部分更新)。参数: | 是 |
| 按 UUID 删除 HAProxy 资源。参数: | 是 |
| 应用待处理的 HAProxy 配置更改 | 是 |
注意: HAProxy 更改不使用保存点保护 — 它们在重新配置时立即生效。始终在
opn_reconfigure_haproxy之前调用opn_haproxy_configtest。
服务(11 个工具)
工具 | 描述 | 写入 |
| ACME/Let's Encrypt 证书及其状态。参数: | 否 |
| 计划中的 cron 作业。参数: | 否 |
| CrowdSec 安全引擎状态和活动决策 | 否 |
| CrowdSec 安全警报(检测到的威胁)。参数: | 否 |
| 动态 DNS 账户及其更新状态。参数: | 否 |
| 创建新的动态 DNS 账户。参数: | 是 |
| 应用待处理的动态 DNS 配置更改 | 是 |
| 更新动态 DNS 账户(密码为只写)。参数: | 是 |
| 按 UUID 删除动态 DNS 账户。参数: | 是 |
| mDNS Repeater 状态和配置(已启用、接口、阻止列表)。需要 | 否 |
| 配置 mDNS Repeater 以实现跨 VLAN 设备发现(HomeKit、Chromecast、AirPlay)。参数: | 是 |
诊断(4 个工具)
工具 | 描述 |
| 从防火墙 ping 主机以测试连通性。参数: |
| 追踪到目的地的网络路径。参数: |
| 从防火墙进行 DNS 查询。参数: |
| 查询活动的 PF 状态表。参数: |
安全(1 个工具)
工具 | 描述 |
| 全面的 11 个领域安全审计:固件、防火墙规则(MVC + 旧版、端口分组、不安全协议)、NAT 转发、DNS 安全(DNSSEC、DoT)、系统加固(SSH、HTTPS、syslog)、服务、证书(ACME + 系统 + CA)、VPN(WireGuard 配置、IPsec、OpenVPN)、HAProxy(标头、健康检查)、网关。发现结果标记有 PCI DSS v4.0、BSI IT-Grundschutz、NIST 800-41、CIS 合规性参考。 |
写入操作和保存点
写入操作需要 OPNSENSE_ALLOW_WRITES=true。在 OPNsense < 26.7 上,防火墙更改还通过 OPNsense 的保存点机制进行:
在任何防火墙更改之前,自动创建保存点
应用更改(规则切换、添加或删除)
60 秒倒计时开始 — 如果未确认,OPNsense 自动还原更改
使用
opn_confirm_changes配合返回的revision使更改永久生效
在这些版本上,如果 AI 助手做出了导致您被锁定的错误防火墙更改,更改会在 60 秒内自动还原。
OPNsense 26.7 上游移除了保存点/回滚 API,因此在 26.7+ 上没有自动还原。 服务器不会硬编码版本截止点:它会在首次防火墙写入时探测保存点端点,如果 OPNsense 回答该端点不存在,则在会话的其余部分降级为直接应用。检查 opn_mcp_info — 其 savepoint_support 字段报告 true、false,如果尚未探测写入则为 null。写入工具随后返回空的 revision,opn_confirm_changes 以 status: "not_applicable" 应答,并且每个防火墙更改都是即时且永久的。
警告: 在 OPNsense 26.7+ 上,在启用写入之前请进行配置备份(
opn_download_config,或 System > Configuration > Backups),并保持对设备的带外访问 — 导致您被锁定的规则不会自行还原。
注意:
opn_reconfigure_unbound、opn_reconfigure_haproxy、opn_reconfigure_ddclient、opn_reconfigure_dnsmasq和opn_configure_mdns_repeater需要写入但不使用保存点 — 它们应用服务配置更改,且不可自动还原。
IPv6 支持
通过 MCP 完全自动化
IPv6 防火墙规则 — 使用
ip_protocol="inet6"创建规则(在 OPNsense < 26.7 上受保存点保护)HAProxy IPv6 绑定 — 前端使用
[::]:443或[2001:db8::1]:443绑定地址HAProxy IPv6 后端 — 服务器使用 IPv6 地址,后端设置
resolvePrefer: ipv6支持 IPv6 的动态 DNS — 使用支持 IPv6 的 checkip 方法的 DDNS 账户
DHCPv6 范围(dnsmasq) — 带有路由器通告配置的 IPv6 DHCP 范围
DNS AAAA 记录 — 使用 IPv6 地址的 Unbound 主机覆盖
IPv6 诊断 — 使用
ip_version="6"的 traceroute,通过主机名 ping
需要手动 GUI 配置
这些设置在 OPNsense 中缺乏 MVC API 支持,必须通过 Web GUI 进行配置:
WAN IPv6 设置 — 使用 DHCPv6 前缀委派的 PPPoE、静态 IPv6、SLAAC
LAN IPv6 寻址 — 跟踪接口模式、静态 /64 分配、前缀 ID
接口分配 — 将物理端口分配给 WAN/LAN/OPT 角色
6to4/6rd 隧道 — 过渡隧道机制
已知限制
ISC DHCP / Kea DHCPv6:未实现。仅支持 dnsmasq(现代默认)用于 DHCPv6 范围和路由器通告。ISC DHCP 已弃用;Kea DHCPv6 租约在 API 中的可见性有限。
radvd:未作为单独的工具集实现。Dnsmasq 通过范围配置原生处理路由器通告。每个接口应只运行一个 RA 守护进程。
双栈防火墙规则:
inet46(双栈)在 MVC API 规则(opn_add_firewall_rule)中正常工作。然而,传统 XML 过滤规则(GUI)中的inet46会静默地不产生 PF 输出——这是已知的 OPNsense 错误,仅影响传统规则。传统 GUI 规则:通过传统 OPNsense GUI 创建的防火墙规则无法通过 MVC API 访问。使用
opn_get_config_section("filter")进行只读访问。
推荐的 IPv6 迁移工作流程
手动(GUI): 配置 WAN IPv6(来自 ISP 的 DHCPv6-PD 或静态)
手动(GUI): 配置 LAN 接口(用于前缀委派的跟踪接口模式)
MCP: 通过
opn_add_dnsmasq_range配置路由器通告,并设置 RA 标志MCP: 创建 IPv6 防火墙规则(必须允许 ICMPv6 以支持 NDP/RA/PMTUD)
MCP: 通过
opn_add_dns_override添加 IPv6 DNS 记录MCP: 配置使用 IPv6 checkip 方法的动态 DNS
MCP: 向 HAProxy 前端添加 IPv6 绑定地址
MCP: 使用
opn_ping、opn_traceroute(ip_version="6")、opn_gateway_status进行验证
版本兼容性
OPNsense 版本 | 状态 |
24.7 (Thriving Tiger) | 支持 |
25.1 (Ultimate Unicorn) | 支持 |
25.7 (Visionary Viper) | 支持(自动检测 snake_case API) |
26.1+ | 支持 |
服务器在首次连接时自动检测 OPNsense 版本,并选择正确的 API 端点命名约定(25.7 之前使用 camelCase,25.7 及之后使用 snake_case)。
关于防火墙规则的说明: opn_list_firewall_rules 显示通过 MVC/自动化 API 管理的规则。通过 OPNsense GUI 配置的规则使用传统格式,无法通过此 API 访问。这是已知的 OPNsense 限制。
故障排除
连接问题
“连接被拒绝”或超时错误
验证
OPNSENSE_URL以/api结尾(例如https://192.168.1.1/api)如果使用非标准端口,请包含端口:
https://192.168.1.1:10443/api确保运行 MCP 服务器的机器可以访问 OPNsense Web GUI
SSL 证书错误
对于自签名证书(OPNsense 默认设置),设置
OPNSENSE_VERIFY_SSL=false对于生产环境,在 OPNsense 上安装合适的证书,并保持
OPNSENSE_VERIFY_SSL=true
身份验证问题
401 未授权
验证
OPNSENSE_API_KEY和OPNSENSE_API_SECRET是否正确API 密钥区分大小写——请从下载的
apikey.txt中准确复制检查 API 用户在 OPNsense 中未被禁用
验证 API 用户具有您尝试执行的操作所需的足够权限
403 禁止
API 用户可能缺少请求端点的权限
对于写操作,确保设置了
OPNSENSE_ALLOW_WRITES=true
工具特定问题
opn_list_firewall_rules 返回空结果
此工具仅显示 MVC/自动化规则,不显示传统 GUI 规则
通过自动化 API 或
opn_add_firewall_rule创建规则以查看它们
opn_ping 超时
防火墙可能没有到目标主机的路由
使用
opn_gateway_status检查网关状态默认超时为 30 秒(30 个轮询周期)
opn_download_config 显示 [REDACTED] 值
这是出于安全考虑的默认行为。传递
include_sensitive=true以包含密码和密钥(在 AI 对话中请谨慎使用)
写操作失败并显示“未启用写入”
在 MCP 服务器配置中设置
OPNSENSE_ALLOW_WRITES=true出于安全考虑,默认情况下有意禁用此功能
保存点确认失败
revision参数必须与写操作返回的内容完全匹配确认必须在 60 秒内完成,否则更改将自动还原
在 OPNsense 26.7+ 上没有保存点 API:写工具返回空的
revision,opn_confirm_changes返回status: "not_applicable"。这是预期行为,不是失败——更改已永久应用
诊断命令
如果您需要调试 MCP 服务器:
# Test API connectivity directly
curl -k -u "your-key:your-secret" https://your-opnsense-ip/api/core/firmware/status
# Run the server directly
python -m opnsense_mcp
# Run tests to verify installation
pytest -v开发
# Clone and install dev dependencies
git clone https://github.com/lucamarien/opnsense-mcp-server
cd opnsense-mcp-server
pip install -e ".[dev]"
# Run all tests (no real OPNsense needed — all tests use mocked API)
pytest -v
# Full CI pipeline (lint, format, type check, security scan, tests)
make validate
# Individual checks
ruff check src/ tests/ # Lint (includes bandit security checks)
ruff format src/ tests/ # Format
mypy src/ --strict # Type checking最佳实践
针对常见防火墙配置任务的领域特定指南:
WhatsApp Calling Firewall Rules — 允许 WhatsApp 语音/视频通话通过默认拒绝防火墙,使用 URL 表别名和范围规则
这些指南展示了真实的 MCP 工具使用模式,并解释了每种方法背后的安全考虑。
贡献
有关详细指南,请参阅 CONTRIBUTING.md。要点:
所有测试必须使用模拟的 API 响应——切勿连接到真实的 OPNsense
工具不得重叠——每个工具必须有明确的用途
编写清晰的文档字符串——它们是 AI 选择工具的唯一指南
返回结构化数据(字典),而不是格式化字符串
提交前运行
make validate
许可证
MIT
Available Tools
81 toolsopn_add_aliasA
Create a new firewall alias (IP list, network group, port group, etc.).
Use this when you need to create a reusable alias for use in firewall rules. Aliases group IPs, networks, or ports under a single name.
This does NOT require savepoint protection — aliases are metadata definitions that only affect traffic when referenced by a firewall rule.
Parameters:
name: alias name (alphanumeric and underscores only, no spaces)
alias_type: 'host' (IPs), 'network' (CIDRs), 'port' (ports/ranges), 'urltable' (URL-based IP list), 'geoip' (country codes)
content: alias entries separated by newlines. For GeoIP, use country codes (one per line, e.g. 'DE\nFR\nNL'). For host/network, use IPs/CIDRs.
description: human-readable description
Returns: dict with 'result' (str) and 'uuid' (str) of the new alias.
Inputs: name (required), content, alias_type, description. Returns: object
opn_add_ddns_accountA
Create a new Dynamic DNS account and apply the configuration.
Use this to register a hostname with a DDNS provider so the firewall automatically updates the DNS record when the public IP changes.
Inputs: service (required), hostname (required), checkip, password, +3 more. Returns: object
opn_add_dnsbl_allowlistA
Add domains to a DNSBL allowlist (whitelist) without overwriting existing entries.
Use this when a domain is blocked by DNSBL and you need to allowlist it (e.g. googleads.g.doubleclick.net blocking YouTube). Existing allowlist entries are preserved. Changes are applied immediately.
Get the UUID from opn_list_dnsbl first.
Parameters:
uuid: blocklist UUID from opn_list_dnsbl
domains: domains to add, comma or newline-separated
Returns: dict with 'added' (list), 'already_present' (list), 'dnsbl_status', and 'service_status'.
Inputs: uuid (required), domains (required). Returns: object
opn_add_dnsmasq_rangeA
Create a new dnsmasq DHCP range and apply the configuration.
Use this to add DHCPv4 or DHCPv6 address ranges with optional Router Advertisement (RA) configuration.
Inputs: end_addr (required), interface (required), start_addr (required), ra_mode, +3 more. Returns: object
opn_add_dns_overrideA
Add an Unbound DNS host override (A/AAAA record) and apply immediately.
Use this when you need to create a local DNS record that resolves a hostname to a specific IP address. Useful for split-horizon DNS, internal services, or overriding external DNS for specific hosts.
Changes are applied immediately (Unbound is reconfigured automatically). DNS overrides cannot be auto-reverted — verify settings before calling. Use opn_list_dns_overrides to check existing overrides first.
Parameters:
hostname: the hostname part (e.g. 'myserver')
domain: the domain part (e.g. 'local.lan')
server: the IP address to resolve to (IPv4 or IPv6)
description: optional description
Returns: dict with 'result', 'uuid', 'hostname', 'server', and 'applied' status.
Inputs: domain (required), server (required), hostname (required), description. Returns: object
opn_add_firewall_categoryA
Create a new firewall rule category.
Use this when you need to create a category for organizing firewall rules. Categories are metadata — creating one does not affect traffic or rules.
Parameters:
name: category name (1-255 chars, no commas)
color: hex color code without '#' (e.g. 'ff0000' for red, default '000000')
Returns: dict with 'result' (str), 'uuid' (str), and 'name' (str).
Inputs: name (required), color. Returns: object
opn_add_firewall_ruleA
Create a new MVC firewall filter rule with savepoint protection where supported.
Use this when you need to add a firewall rule.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
IMPORTANT: This creates MVC rules (Settings > Firewall > Automation), not legacy GUI rules.
Parameters:
action: 'pass', 'block', or 'reject'
direction: 'in' or 'out'
interface: interface name (e.g. 'lan', 'wan', 'opt1')
ip_protocol: 'inet' (IPv4), 'inet6' (IPv6), or 'inet46' (dual-stack)
protocol: 'any', 'TCP', 'UDP', 'TCP/UDP', 'ICMP', etc.
source_net: source address/network or 'any'
source_not: invert source match (True = NOT source_net)
source_port: source port number or range, or empty for any
destination_net: destination address/network or 'any'
destination_not: invert destination match (True = NOT destination_net, e.g. !Private_Networks)
destination_port: port number or range (e.g. '80', '1000-2000'), or empty for any
gateway: force traffic via specific gateway (e.g. 'WAN_GW') for policy routing, or empty for default
log: enable logging for this rule (default: off)
quick: first-match wins (default: True). Set False for last-match-wins logic
sequence: rule ordering within priority group (default: 1, higher = later)
categories: comma-separated category UUIDs to assign to this rule
description: human-readable rule description
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: log, quick, action, gateway, +13 more. Returns: object
opn_add_icmpv6_rulesA
Create essential ICMPv6 firewall rules required for IPv6 operation.
Use this when setting up IPv6 on an interface. ICMPv6 is MANDATORY for IPv6 — without it, Neighbor Discovery (NDP), Router Advertisements (RA), and Path MTU Discovery (PMTUD) all break.
Creates 5 rules per RFC 4890:
NDP Neighbor Solicitation (link-local -> multicast)
NDP Neighbor Advertisement (link-local -> any)
NDP Router Solicitation (link-local -> all-routers multicast)
NDP Router Advertisement (link-local -> all-nodes multicast)
ICMPv6 Echo (ping6) inbound
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
Parameters:
interface: target interface (e.g. 'lan', 'opt1', 'opt2')
Returns: dict with 'revision' (str), 'rules' (list of created UUIDs), and instructions to confirm.
Inputs: interface. Returns: object
opn_add_nat_ruleA
Create a NAT port forwarding rule with savepoint protection where supported.
Use this when you need to forward an external port to an internal host. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
Parameters:
destination_port: external port to forward (e.g. '8080', '3000-3010') — required
target_ip: internal IP address to forward to (e.g. '192.168.1.100') — required
interface: source interface (default 'wan')
protocol: 'TCP', 'UDP', or 'TCP/UDP' (default 'TCP')
target_port: internal port (default: same as destination_port)
description: human-readable description
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: protocol, interface, target_ip, description, +2 more. Returns: object
opn_arp_tableA
Get the ARP table showing IP-to-MAC address mappings.
Use this when you need to find which MAC address is associated with an IP, identify devices on a network segment, or troubleshoot connectivity. Returns: dict with 'rows' (list of ARP entries including ip, mac, intf, and hostname fields) and 'rowCount' (total).
Inputs: no named parameters. Returns: object
opn_configure_mdns_repeaterA
Enable and configure the mDNS Repeater to relay multicast DNS between interfaces.
Use this to set up cross-VLAN mDNS discovery. The repeater relays mDNS packets (224.0.0.251:5353) between selected interfaces, enabling HomeKit, Chromecast, AirPlay, and other mDNS-based device discovery across VLANs.
Inputs: enabled, interfaces. Returns: object
opn_confirm_changesA
Confirm pending firewall changes, cancelling the 60-second auto-rollback.
Use this AFTER applying firewall changes (rule add/edit/delete) to make them permanent. If not called within 60 seconds of applying, OPNsense automatically reverts all changes for safety.
Only relevant on OPNsense < 26.7. Newer versions have no savepoint API; there the write tools return an empty revision and this call is a no-op. Returns: dict with confirmation status, or status 'not_applicable'.
Inputs: revision (required). Returns: object
opn_crowdsec_alertsA
List CrowdSec security alerts (detected threats and attacks).
Use this when you need to review security events detected by CrowdSec, including brute-force attempts, port scans, and other threats. Note: Requires the CrowdSec plugin (os-crowdsec). Returns: dict with 'rows' (list of alerts) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_crowdsec_statusA
Get CrowdSec security engine status and active decisions summary.
Use this when you need to check if CrowdSec is running, see how many active security decisions (bans/captchas) are in effect, and get a quick overview of the threat protection state. Note: Requires the CrowdSec plugin (os-crowdsec). Returns: dict with 'service_status', 'decisions_count', and 'alerts_count'.
Inputs: no named parameters. Returns: object
opn_delete_aliasA
Delete a firewall alias by UUID.
IMPORTANT: Check if any firewall rules reference this alias BEFORE deleting. Deleting an alias that is referenced by rules may cause those rules to stop matching traffic. Use opn_list_firewall_rules to check for references first.
This does NOT use savepoint protection — aliases are metadata definitions. The deletion takes effect immediately.
Use opn_list_firewall_aliases first to find the UUID. Returns: dict with 'result' (str) and 'uuid' (str).
Inputs: uuid (required). Returns: object
opn_delete_ddns_accountA
Delete a Dynamic DNS account by UUID and apply the configuration.
The deletion is applied immediately (ddclient is reconfigured automatically). Use opn_list_ddns_accounts first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required). Returns: object
opn_delete_dnsmasq_rangeA
Delete a dnsmasq DHCP range by UUID and apply the configuration.
The deletion is applied immediately (dnsmasq is reconfigured automatically). Use opn_list_dnsmasq_ranges first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required). Returns: object
opn_delete_dns_overrideA
Delete an Unbound DNS host override by UUID and apply immediately.
The deletion is applied immediately (Unbound is reconfigured automatically). DNS changes cannot be auto-reverted — verify the UUID before calling. Use opn_list_dns_overrides first to find the UUID. Returns: dict with 'result' (str), 'uuid' (str), and 'applied' status.
Inputs: uuid (required). Returns: object
opn_delete_firewall_categoryA
Delete a firewall rule category by UUID with savepoint protection where supported.
IMPORTANT: Reassign rules to other categories BEFORE deleting to avoid orphaned category references. Use opn_list_firewall_categories to find categories and opn_set_rule_categories to reassign rules first.
System default categories (auto=1) cannot be deleted. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Returns: dict with 'revision' (str) for confirming and 'result' (str).
Inputs: uuid (required). Returns: object
opn_delete_firewall_ruleA
Delete a firewall filter rule by UUID with savepoint protection where supported.
Use this when you need to remove an existing MVC firewall rule.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID of the rule to delete. Returns: dict with 'revision' (str) for confirming and 'result' (str).
Inputs: uuid (required). Returns: object
opn_delete_nat_ruleA
Delete a NAT port forwarding rule by UUID with savepoint protection where supported.
Use this when you need to remove an existing NAT rule.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_nat_rules first to find the UUID of the rule to delete. Returns: dict with 'revision' (str) for confirming and 'result' (str).
Inputs: uuid (required). Returns: object
opn_dns_lookupA
Perform a DNS lookup from the OPNsense firewall.
Use this when you need to test DNS resolution from the firewall's perspective, verify Unbound is resolving correctly, or check if a specific DNS server returns expected results. Returns: dict with 'result' (str) and 'response' (DNS query results).
Inputs: hostname (required), server. Returns: object
opn_dns_statsA
Get Unbound DNS resolver statistics (queries, cache hits, uptime).
Use this when you need to check DNS resolver performance, cache hit rates, or troubleshoot DNS resolution issues. Returns: dict with resolver statistics fields.
Inputs: no named parameters. Returns: object
opn_download_configA
Download OPNsense config.xml backup as raw XML.
Use this ONLY when you need a full XML backup for archival purposes. For analyzing specific config sections, use opn_scan_config to build a cached inventory, then opn_get_config_section to query individual sections.
By default, sensitive data (passwords, keys, secrets) is redacted; a config that cannot be parsed for redaction is refused, never returned raw. include_sensitive=true additionally requires OPNSENSE_ALLOW_SENSITIVE=true in the server environment — without it, the call is refused. Returns: dict with 'config_xml' (str), 'stripped' (bool), 'size_bytes' (int), or 'error'/'error_type' when the config cannot be parsed.
Inputs: include_sensitive. Returns: object
opn_firewall_logA
Get recent firewall log entries (blocked and passed packets).
Use this when you need to check what traffic has been blocked or passed, troubleshoot connectivity issues, or audit firewall activity. All filter parameters are optional substring matches applied client-side. Returns: dict with 'entries' (list of log rows) and 'total' (count after filtering).
Inputs: limit, action, interface, source_ip, +1 more. Returns: object
opn_gateway_statusA
Get gateway status including dpinger health checks.
Use this when you need to check if WAN gateways are up, their latency, packet loss, or failover state. Returns: dict with gateway items including status, loss, and delay fields. (If the API answers with a bare array, it arrives wrapped in the 'rows'/'rowCount' envelope.)
Inputs: no named parameters. Returns: object
opn_get_config_sectionA
Get a specific configuration section as structured JSON.
Use this after opn_scan_config to drill into a specific area of the OPNsense configuration. If the config hasn't been scanned yet, it will be loaded automatically.
Available sections vary by OPNsense installation. Common sections include: system, interfaces, vlans, filter (legacy firewall rules), nat, OPNsense (MVC plugin config), unbound, dnsmasq, dhcpd, staticroutes, syslog.
The 'filter' section is particularly useful — it contains legacy GUI firewall rules that are NOT visible via opn_list_firewall_rules.
Sensitive values are redacted by default; include_sensitive=true requires OPNSENSE_ALLOW_SENSITIVE=true in the server environment. Returns: dict with 'section' name and 'data' (structured config data).
Inputs: section (required), include_sensitive. Returns: object
opn_get_dnsblA
Get full DNSBL configuration for a specific blocklist by UUID.
Use this when you need to see all available providers and their selection state, current allowlist/blocklist entries, and other DNSBL settings. Get the UUID from opn_list_dnsbl first.
Returns: dict with 'selected_providers', 'available_providers', 'allowlists', 'blocklists', 'wildcards', and config fields.
Inputs: uuid (required). Returns: object
opn_haproxy_addA
Create a new HAProxy resource.
Use this to add frontends, backends, servers, actions, ACLs, health checks, error files, resolvers, or mailers.
The config dict contains field name-value pairs. Only specify fields you want to set — the API fills in defaults for omitted fields.
Health check example:
config={"name": "hc_web", "type": "http", "interval": "5000", "checkport": "8080", "http_method": "get", "http_uri": "/", "http_version": "http11"}
For apps returning non-2xx (e.g. 401 behind auth), add: "http_expressionEnabled": "1", "http_expression": "rstatus", "http_value": "^[2-4][0-9]{2}$"
After creating, link to a backend with opn_haproxy_update: config={"healthCheck": ""}
IPv6 examples:
Frontend bind: config={"name": "web-v6", "bind": "[::]:443,0.0.0.0:443", "mode": "http", "ssl_enabled": "1", "defaultBackend": ""}
Server address: config={"name": "srv1", "address": "2001:db8::1", "port": "8080"}
Backend resolvePrefer: config={"name": "pool1", "mode": "http", "algorithm": "roundrobin", "resolvePrefer": "ipv6"}
NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy. Call opn_haproxy_configtest first to validate the configuration.
Returns: dict with 'result' (str) and 'uuid' (str) of the new resource.
Inputs: config (required), resource_type (required). Returns: object
opn_haproxy_configtestA
Validate HAProxy configuration syntax before applying.
Use this BEFORE calling opn_reconfigure_haproxy to verify the configuration is valid. This runs 'haproxy -c' internally and reports any syntax errors.
Returns: dict with validation result (typically 'status' key).
Inputs: no named parameters. Returns: object
opn_haproxy_deleteA
Delete a HAProxy resource by UUID.
IMPORTANT: Check for dependencies before deleting:
Delete servers before deleting backends that reference them
Delete actions/ACLs before deleting frontends/backends that link them
Delete backends before deleting frontends that use them as defaultBackend
Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.
NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy.
Returns: dict with 'result' indicating success.
Inputs: uuid (required), resource_type (required). Returns: object
opn_haproxy_getA
Get detailed configuration for a specific HAProxy resource.
Use this to inspect all fields of a single resource before modifying it. Returns the full field set including SSL, tuning, persistence, and linked resources.
Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.
Returns: dict with the resource type as key containing all field values.
Inputs: uuid (required), resource_type (required). Returns: object
opn_haproxy_searchA
Search HAProxy resources by type.
Use this to list and search any HAProxy resource. All resource types use the same paginated search pattern.
Resource types and their key fields:
frontends: name, bind (IPv6: [::]:443), mode (http/ssl/tcp), ssl_enabled, defaultBackend
backends: name, mode, algorithm (roundrobin/leastconn/source), linkedServers, healthCheck
servers: name, address (IPv4/IPv6), port, mode (active/backup/disabled), weight, ssl
actions: name, testType, operator (AND/OR), linkedAcls, useBackend
acls: name, expression, negate
healthchecks: name, type (http/tcp/agent/ldap/mysql/pgsql/redis/smtp), interval
errorfiles: name, code (HTTP status), content
resolvers: name, nameserver, timeout
mailers: name, mailserver, port
Returns: dict with 'rows' (list of resources) and 'rowCount' (total).
Inputs: resource_type (required), limit, search. Returns: object
opn_haproxy_statusA
Get HAProxy load balancer status and backend health.
Use this when you need to check HAProxy server status, backend availability, or connection statistics. Note: Requires the HAProxy plugin (os-haproxy). Returns: dict with HAProxy status including servers and backends.
Inputs: no named parameters. Returns: object
opn_haproxy_updateA
Update an existing HAProxy resource.
Use this to modify any field on a HAProxy resource. Only provide the fields you want to change — omitted fields keep their current values.
To enable/disable a resource, set config={"enabled": "1"} or {"enabled": "0"}.
Resource types: frontends, backends, servers, actions, acls, healthchecks, errorfiles, resolvers, mailers.
NOTE: Changes are NOT applied until you call opn_reconfigure_haproxy. Call opn_haproxy_configtest first to validate the configuration.
Returns: dict with 'result' indicating success.
Inputs: uuid (required), config (required), resource_type (required). Returns: object
opn_interface_statsA
Get per-interface traffic statistics (bytes in/out, packets, errors).
Use this when you need to see network utilization, check for interface errors, or compare traffic across interfaces. Returns: dict with 'statistics' (per-interface counters keyed by interface label).
Inputs: no named parameters. Returns: object
opn_ipsec_statusA
Get IPsec VPN tunnel status (IKE and ESP phases).
Use this when you need to check IPsec site-to-site tunnel health, see connected peers, or troubleshoot VPN connectivity. Shows both Phase 1 (IKE negotiation) and Phase 2 (ESP/AH tunnels). Note: Requires IPsec to be configured. Based on strongSwan (OPNsense 23.1+). Returns: dict with 'service_status', 'phase1' (IKE sessions), and 'phase2' (tunnels).
Inputs: no named parameters. Returns: object
opn_ipv6_statusA
Get IPv6 configuration and address status for all interfaces.
Use this when you need a quick overview of which interfaces have IPv6 configured, what addresses are assigned, and the IPv6 method (DHCPv6-PD, Track Interface, SLAAC, static).
Returns: dict with 'interfaces' (list of per-interface IPv6 info) and 'summary' (counts of configured/unconfigured interfaces).
Inputs: no named parameters. Returns: object
opn_list_acme_certsA
List ACME (Let's Encrypt) certificates and their status.
Use this when you need to check certificate expiry dates, renewal status, or which domains have ACME certificates configured. Note: Requires the ACME client plugin (os-acme-client). Returns: dict with 'rows' (list of certificates) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_cron_jobsA
List scheduled cron jobs configured in OPNsense.
Use this when you need to check what scheduled tasks are configured, their frequency, or which commands they run. Returns: dict with 'rows' (list of cron jobs) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_ddns_accountsA
List Dynamic DNS (DDNS) accounts and their update status.
Use this to check which hostnames have DDNS configured, their current IP addresses, last update time, and which service provider is used.
Key fields: service (provider), hostname, checkip (method), current_ip, current_mtime (last update), interface, enabled.
For IPv6 DDNS: the global setting 'allowipv6' must be enabled AND an IPv6-capable checkip method must be used (e.g. 'cloudflare-ipv6'). Both must be set or IPv6 updates silently fail.
Note: Requires the Dynamic DNS plugin (os-ddclient). Returns: dict with 'rows' (list of accounts) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dhcp_leasesA
List current DHCPv4 leases from the ISC DHCP server (legacy).
Use this when the OPNsense instance uses the ISC DHCP plugin (os-isc-dhcp). ISC DHCP is legacy and being phased out — most 26.x instances use dnsmasq or Kea. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with DHCP lease entries including address, mac, and hostname fields. (If the API answers with a bare array, it arrives wrapped in the 'rows'/'rowCount' envelope.)
Inputs: no named parameters. Returns: object
opn_list_dnsblA
List DNSBL (DNS Blocklist) configurations with providers and status.
Use this when you need to see which DNS blocklists are configured, which providers are active, and what allowlist/blocklist entries exist. Use opn_get_dnsbl with a UUID from the results for full details. Returns: dict with 'rows' (list of blocklist configs) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dns_forwardsA
List Unbound DNS forward zones (domain-specific DNS servers).
Use this when you need to check which domains are forwarded to specific upstream DNS servers or DNS-over-TLS resolvers. Returns: dict with 'rows' (list of forward zones) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dnsmasq_leasesA
List current DHCPv4 and DHCPv6 leases from the dnsmasq DNS/DHCP server.
Use this when the OPNsense instance uses dnsmasq for DHCP (default in 26.x). dnsmasq is a lightweight combined DNS/DHCP server that handles both DHCPv4 and DHCPv6. IPv6 leases appear alongside IPv4 leases in the results. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with 'rows' (list of leases) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dnsmasq_rangesA
List dnsmasq DHCP ranges (both DHCPv4 and DHCPv6 with RA config).
Use this to see configured DHCP address pools and Router Advertisement settings for each interface. Both IPv4 and IPv6 ranges appear in the same list.
Key fields: interface, start_addr, end_addr, prefix_len (IPv6) or subnet_mask (IPv4), ra_mode (slaac/ra-stateless/ra-only), ra_priority, lease_time, enabled.
Note: Requires the dnsmasq DNS/DHCP server (os-dnsmasq-dns or built-in). Returns: dict with 'rows' (list of ranges) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_dns_overridesB
List Unbound DNS host overrides (local DNS records).
Use this when you need to see which hostnames are overridden to specific IP addresses in the local DNS resolver. Returns: dict with 'rows' (list of overrides) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_firewall_aliasesA
List firewall alias definitions (IP lists, port groups, GeoIP, URLs).
Use this when you need to see which aliases are defined, their types, or what IP addresses/networks they resolve to. Returns: dict with 'rows' (list of aliases) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_firewall_categoriesA
List firewall rule categories.
Use this when you need to see which categories exist, check their names and colors, or find category UUIDs for assigning to rules. Returns: dict with 'rows' (list of categories) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_firewall_rulesA
List firewall filter rules configured via the MVC API.
IMPORTANT: This only returns rules created through the OPNsense MVC filter API (Settings > Firewall > Automation). Legacy rules configured via the traditional GUI (Firewall > Rules) are NOT visible through this endpoint. Most users have legacy rules — a result of 0 rules does not mean no rules exist.
Use this when you need to inspect MVC-managed firewall filter rules. Returns: dict with 'rows' (list of rules) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_kea_leasesA
List current DHCPv4 leases from the Kea DHCP server.
Use this when the OPNsense instance uses Kea for DHCP (available since 24.7). Kea is the modern replacement for ISC DHCP, recommended for HA setups. Use opn_scan_config first to check which DHCP backend is active. Returns: dict with 'rows' (list of leases) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_nat_rulesA
List NAT port forwarding (DNAT) rules.
Use this when you need to see which ports are forwarded to internal hosts, check NAT rule configuration, or troubleshoot port forwarding issues.
Like firewall filter rules, this only returns MVC-managed NAT rules. Legacy NAT rules from the traditional GUI may not appear here — use opn_get_config_section('nat') to see all NAT configuration.
Returns: dict with 'rows' (list of NAT rules) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_servicesA
List system services and their running status.
Use this when you need to check which services are running, stopped, or available on the OPNsense instance. Returns: dict with 'rows' (list of services) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_list_static_routesA
List configured static routes.
Use this when you need to see custom routing table entries, check which networks are routed through which gateways, or troubleshoot routing issues. Note: This shows configured static routes, not the full kernel routing table. Returns: dict with 'rows' (list of static routes) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_mcp_infoA
Get MCP server version and runtime configuration.
Use this to check the MCP server version, whether write mode is enabled, the detected OPNsense API version, and whether firewall writes still get savepoint/rollback protection. Version detection runs here if no earlier call triggered it; if the firewall is unreachable, the failure is reported instead of raised. Returns: dict with 'mcp_version', 'write_mode', 'opnsense_version', 'api_style', 'savepoint_support' and, only when detection failed, 'version_detection_error'. 'savepoint_support' is true when the 60-second auto-revert is available, false when OPNsense no longer offers it (26.7+ removed it upstream, so firewall changes are immediate and permanent), and null when no firewall write has probed for it yet.
Inputs: no named parameters. Returns: object
opn_mdns_repeater_statusA
Get mDNS Repeater service status and configuration.
Use this to check if the mDNS Repeater is installed, enabled, running, and which interfaces it is configured to relay multicast DNS between.
The mDNS Repeater relays mDNS (224.0.0.251:5353) packets between selected interfaces, enabling device discovery (HomeKit, Chromecast, AirPlay, etc.) across VLANs.
Note: Requires the mDNS Repeater plugin (os-mdns-repeater). Returns: dict with 'service_running', 'enabled', 'interfaces', 'blocklist'.
Inputs: no named parameters. Returns: object
opn_ndp_tableA
Get the NDP table showing IPv6-to-MAC address mappings.
Use this when you need to find which MAC address is associated with an IPv6 address, identify IPv6-enabled devices on a network segment, or troubleshoot IPv6 neighbor reachability. This is the IPv6 equivalent of the ARP table. Returns: dict with 'rows' (list of NDP entries including ip, mac, intf, and manufacturer fields) and 'rowCount' (total).
Inputs: no named parameters. Returns: object
opn_openvpn_statusA
Get OpenVPN connection status (instances, sessions, routes).
Use this when you need to check OpenVPN server/client status, see connected clients, active VPN routes, or troubleshoot OpenVPN tunnels. Note: OpenVPN is built-in (no plugin needed) but must be configured. Returns: dict with 'instances', 'sessions' (connected clients), and 'routes'.
Inputs: no named parameters. Returns: object
opn_pf_statesA
Query the active PF (packet filter) state table.
Use this when you need to see active connections through the firewall, debug NAT issues, or identify which hosts are communicating. Returns: dict with 'rows' (list of state entries) and 'rowCount' (total).
Inputs: limit, search. Returns: object
opn_pingA
Ping a host from the OPNsense firewall to test connectivity.
Use this when you need to check if a host is reachable from the firewall, measure round-trip latency, or diagnose network connectivity issues. The ping runs on the firewall itself, not locally. Returns: dict with ping results including loss percentage and RTT stats.
Inputs: host (required), count. Returns: object
opn_reconfigure_ddclientA
Apply pending Dynamic DNS configuration changes.
Use this after manually editing DDNS account settings to apply the changes to the running ddclient service.
Note: opn_add_ddns_account auto-reconfigures, so this is only needed for manual edits or troubleshooting.
Note: Requires the Dynamic DNS plugin (os-ddclient). Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_reconfigure_dnsmasqA
Apply pending dnsmasq DNS/DHCP configuration changes.
Use this after manually editing dnsmasq settings to apply the changes to the running dnsmasq service.
Note: opn_add_dnsmasq_range auto-reconfigures, so this is only needed for manual edits or troubleshooting.
Note: Requires the dnsmasq DNS/DHCP server. Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_reconfigure_haproxyA
Apply pending HAProxy load balancer configuration changes.
Use this after making HAProxy configuration changes to apply them to the running HAProxy service. This reconfigures HAProxy with the new settings.
NOTE: This does not use savepoint protection. HAProxy changes take effect immediately. Requires the HAProxy plugin (os-haproxy). IMPORTANT: Do NOT call haproxy/service/start after reconfigure — reconfigure already starts the service, and start will error if already running. IMPORTANT: Always call opn_haproxy_configtest before reconfiguring to validate the configuration syntax. Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_reconfigure_unboundA
Apply pending Unbound DNS resolver configuration changes.
Use this after making DNS configuration changes (adding overrides, forward zones, etc.) to apply them to the running Unbound service. This restarts Unbound with the new configuration.
NOTE: This does not use savepoint protection. DNS changes take effect immediately and cannot be auto-reverted. Verify settings before calling. Returns: dict with 'status' indicating success or failure.
Inputs: no named parameters. Returns: object
opn_remove_dnsbl_allowlistA
Remove domains from a DNSBL allowlist.
Use this when you no longer need a domain allowlisted and want to re-enable DNSBL blocking for it. Changes are applied immediately.
Get the UUID from opn_list_dnsbl first.
Parameters:
uuid: blocklist UUID from opn_list_dnsbl
domains: domains to remove, comma or newline-separated
Returns: dict with 'removed' (list), 'not_found' (list), 'dnsbl_status', and 'service_status'.
Inputs: uuid (required), domains (required). Returns: object
opn_scan_configA
Scan the OPNsense configuration and build a cached inventory.
Use this FIRST when starting a new session. Downloads the full config, parses it into queryable sections, and detects runtime state (services, DHCP backend, DNS servers). Results are cached for the session — subsequent calls return the cached version unless force=True.
Call with force=True to rescan after manual config changes on the firewall. Use opn_get_config_section(section) to drill into specific sections.
Returns: dict with 'firmware', 'plugins', 'dhcp', 'dns', 'interfaces', 'services', and 'config_sections' (list of available sections with sizes).
Inputs: force. Returns: object
opn_security_auditA
Run a comprehensive security audit of the OPNsense firewall.
Checks 11 security areas: firmware, firewall rules (MVC + legacy), NAT/port forwarding, DNS resolver security, system hardening (SSH, HTTPS, syslog), services, certificates, VPN status (incl. WireGuard config audit), HAProxy reverse proxy security, and gateway health.
Findings are tagged with applicable compliance frameworks: PCI DSS v4.0, BSI IT-Grundschutz, NIST SP 800-41, CIS Benchmarks.
Returns a structured audit report with findings categorized by severity (critical, warning, info). Each finding includes a recommendation and applicable compliance framework references.
Use this when you need to assess the security posture of the firewall, identify misconfigurations, or perform a routine health check.
Inputs: no named parameters. Returns: object
opn_set_dnsblA
Update a DNSBL blocklist configuration (read-modify-write).
Use this when you need to change DNSBL settings — providers, allowlists, blocklists, etc. Only the parameters you provide are changed; all other settings are preserved. Changes are applied immediately.
Get the UUID from opn_list_dnsbl first.
Parameters:
uuid: blocklist UUID from opn_list_dnsbl
enabled: enable/disable this blocklist
providers: comma-separated provider shortcodes (e.g. 'hgz002,hgz011,ag')
custom_urls: newline-separated custom blocklist URLs
allowlists: newline-separated allowlist entries (domains or regex patterns)
blocklists: newline-separated custom block domains
wildcards: newline-separated wildcard block domains
source_nets: comma-separated source networks (empty = all)
nxdomain: return NXDOMAIN instead of 0.0.0.0 for blocked domains
cache_ttl: cache TTL in seconds for DNSBL responses
description: human-readable description
Returns: dict with 'result', 'dnsbl_status', and 'service_status'.
Inputs: uuid (required), enabled, nxdomain, cache_ttl, +7 more. Returns: object
opn_set_rule_categoriesA
Assign categories to a firewall rule by UUID with savepoint protection where supported.
Use this when you need to categorize or re-categorize a firewall rule. Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out.
Parameters:
uuid: the firewall rule UUID (from opn_list_firewall_rules)
categories: comma-separated category UUIDs (from opn_list_firewall_categories), or empty string to clear all categories
Returns: dict with 'revision' (str) for confirming and 'uuid' (str).
Inputs: uuid (required), categories. Returns: object
opn_system_statusA
Get OPNsense system status including firmware version and product info.
Use this when you need to check the current firmware version, system name, or verify the OPNsense appliance is reachable and responding. Returns: dict with firmware/product info. On OPNsense 26.x+, product fields are nested under a 'product' key; earlier versions have them at the top level.
Inputs: no named parameters. Returns: object
opn_toggle_aliasA
Toggle a firewall alias's enabled/disabled state.
Use this when you need to temporarily disable an alias without deleting it, or re-enable a previously disabled alias. The toggle flips the current state.
This does NOT use savepoint protection — aliases are metadata definitions. Use opn_list_firewall_aliases first to find the UUID. Returns: dict with 'result' (str) and 'uuid' (str).
Inputs: uuid (required). Returns: object
opn_toggle_firewall_ruleA
Toggle a firewall filter rule's enabled/disabled state with savepoint protection where supported.
Use this when you need to temporarily disable a rule for testing or re-enable a previously disabled rule. The toggle flips the current state.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID of the rule. Returns: dict with 'revision' (str) for confirming and 'uuid' (str).
Inputs: uuid (required). Returns: object
opn_tracerouteB
Trace the network path from OPNsense to a destination host.
Use this when you need to diagnose routing issues, identify where packets are being dropped, or visualize the network hops to a destination. Returns: dict with 'result' (str) and 'response' (list of hops).
Inputs: host (required), protocol, ip_version. Returns: object
opn_update_aliasA
Update an existing firewall alias by UUID (read-modify-write).
Use this when you need to rename an alias, change its content (IPs, networks, ports), modify its description, or change its type. Only the parameters you provide are changed; all other settings are preserved.
This does NOT require savepoint protection — aliases are metadata definitions that only affect traffic when referenced by a firewall rule.
Use opn_list_firewall_aliases first to find the UUID.
Parameters:
uuid: alias UUID (from opn_list_firewall_aliases)
name: new alias name (alphanumeric and underscores only)
content: new alias entries separated by newlines
description: new description
alias_type: new type ('host', 'network', 'port', 'urltable', 'geoip')
enabled: enable/disable the alias
Returns: dict with 'result' (str) and 'uuid' (str).
Inputs: uuid (required), name, content, enabled, +2 more. Returns: object
opn_update_ddns_accountA
Update a Dynamic DNS account by UUID and apply the configuration.
Use this when you need to change the hostname, provider, credentials, or other properties of a DDNS account. Only the parameters you provide are changed; all other settings are preserved.
After update, the ddclient service is automatically reconfigured. Changes take effect immediately. Use opn_list_ddns_accounts first to find the UUID.
Parameters:
uuid: account UUID (from opn_list_ddns_accounts)
service: DDNS provider name (e.g. 'cloudflare', 'dyndns', 'noip')
hostname: fully qualified domain name to update
username: provider username or API key
password: provider password or API token
checkip: IP check method (e.g. 'web_dyndns', 'if')
interface: network interface name (e.g. 'wan')
description: human-readable description
enabled: enable/disable the account
Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required), checkip, enabled, service, +5 more. Returns: object
opn_update_dnsblA
Reload DNSBL blocklist files and restart Unbound to apply them.
Use this when DNSBL lists need to be refreshed without changing the configuration — for example after a service restart that lost loaded lists, or to force Unbound to pick up previously generated blocklist files. This flushes the DNS cache, so previously cached blocked (or unblocked) domains will be re-evaluated.
NOTE: This does not use savepoint protection. DNS changes take effect immediately and cannot be auto-reverted. Returns: dict with 'dnsbl_status' and 'service_status'.
Inputs: no named parameters. Returns: object
opn_update_dnsmasq_rangeA
Update a dnsmasq DHCP range by UUID and apply the configuration.
Use this when you need to change the address range, lease time, RA settings, or other properties. Only the parameters you provide are changed; all other settings are preserved.
After update, the dnsmasq service is automatically reconfigured. Changes take effect immediately. Use opn_list_dnsmasq_ranges first to find the UUID.
Parameters:
uuid: range UUID (from opn_list_dnsmasq_ranges)
interface: network interface name (e.g. 'lan', 'opt1')
start_addr: start of address range
end_addr: end of address range
prefix_len: IPv6 prefix length (e.g. '64')
ra_mode: Router Advertisement mode ('slaac', 'ra-stateless', 'ra-only')
lease_time: lease duration (e.g. '24h', '1h')
description: human-readable description
enabled: enable/disable the range
Returns: dict with 'result' (str), 'uuid' (str), and 'reconfigure_status'.
Inputs: uuid (required), enabled, ra_mode, end_addr, +5 more. Returns: object
opn_update_dns_overrideA
Update an Unbound DNS host override by UUID and apply immediately.
Use this when you need to change the hostname, domain, IP address, or other properties of a DNS override. Only the parameters you provide are changed; all other settings are preserved.
Changes are applied immediately (Unbound is reconfigured automatically). DNS overrides cannot be auto-reverted — verify settings before calling. Use opn_list_dns_overrides first to find the UUID.
Parameters:
uuid: override UUID (from opn_list_dns_overrides)
hostname: new hostname part (e.g. 'myserver')
domain: new domain part (e.g. 'local.lan')
server: new IP address (IPv4 or IPv6)
description: new description
enabled: enable/disable the override
Returns: dict with 'result' (str), 'uuid' (str), and 'applied' status.
Inputs: uuid (required), domain, server, enabled, +2 more. Returns: object
opn_update_firewall_ruleA
Update an existing MVC firewall rule by UUID with savepoint protection where supported.
Use this when you need to modify a firewall rule's action, source/destination, protocol, ports, or other properties. Only the parameters you provide are changed; all other settings are preserved.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_firewall_rules first to find the UUID.
Parameters:
uuid: rule UUID (from opn_list_firewall_rules)
action: 'pass', 'block', or 'reject'
direction: 'in' or 'out'
interface: interface name (e.g. 'lan', 'wan', 'opt1')
ip_protocol: 'inet' (IPv4), 'inet6' (IPv6), or 'inet46' (dual-stack)
protocol: 'any', 'TCP', 'UDP', 'TCP/UDP', 'ICMP', etc.
source_net: source address/network or 'any'
source_not: invert source match
source_port: source port number or range
destination_net: destination address/network or 'any'
destination_not: invert destination match
destination_port: port number or range
gateway: force traffic via specific gateway, or empty to clear
log: enable/disable logging
quick: first-match wins (True) or last-match-wins (False)
sequence: rule ordering within priority group
categories: comma-separated category UUIDs
description: human-readable rule description
enabled: enable/disable the rule
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: uuid (required), log, quick, action, +15 more. Returns: object
opn_update_nat_ruleA
Update an existing NAT port forwarding rule by UUID with savepoint protection where supported.
Use this when you need to change the target IP, port, or other properties of a NAT rule. Only the parameters you provide are changed; all other settings are preserved.
Savepoint protection applies on OPNsense < 26.7 only: there changes auto-revert in 60 seconds unless confirmed with opn_confirm_changes. OPNsense 26.7 removed the savepoint API upstream, so on 26.7+ changes apply immediately and are NOT rolled back automatically. Check opn_mcp_info first: if 'savepoint_support' is false, take a config backup with opn_download_config before changing rules that could lock you out. Use opn_list_nat_rules first to find the UUID.
Parameters:
uuid: NAT rule UUID (from opn_list_nat_rules)
interface: source interface (e.g. 'wan', 'opt1')
protocol: 'TCP', 'UDP', or 'TCP/UDP'
destination_port: external port to forward (e.g. '8080', '3000-3010')
target_ip: internal IP address to forward to
target_port: internal port
description: human-readable description
enabled: enable/disable the rule
Returns: dict with 'revision' (str), 'uuid' (str), and 'result' (str).
Inputs: uuid (required), enabled, protocol, interface, +4 more. Returns: object
opn_wireguard_statusA
Get WireGuard VPN tunnel and peer status.
Use this when you need to check WireGuard tunnel health, peer handshake times, transferred bytes, or endpoint information. Note: Requires the WireGuard plugin (os-wireguard). Returns: dict with tunnel and peer details including endpoints and transfer stats.
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 81 tools
Most tools are clearly separated by resource and action, and descriptions explicitly warn about MVC vs legacy firewall rules and backend-specific DHCP lease tools. A few areas remain confusable, especially the three DHCP lease listings, opn_set_dnsbl vs opn_update_dnsbl, and the various HAProxy reconfigure/configtest/status tools.
The opn_ prefix is used throughout and most names follow a predictable action_resource pattern such as opn_list_firewall_rules and opn_add_nat_rule. Minor deviations exist, including HAProxy's resource-first naming, alias singular/plural inconsistency, and opn_update_dnsbl meaning 'reload' rather than update configuration.
81 tools is an extreme number for a single MCP server and far beyond the typical 3-15 well-scoped range. While OPNsense is broad, this surface is large enough to make discovery and correct selection burdensome for an agent.
Core areas such as firewall rules, aliases, NAT, DNS overrides, DNSMasq ranges, DDNS, and HAProxy have substantial CRUD coverage, while several other areas are only partially covered. Static routes, services, cron jobs, ACME certificates, and most VPN configuration are read-only or status-only, leaving notable lifecycle gaps.
Maintenance
Related MCP Connectors
Security-first WordPress MCP server. 129 tools for Claude, ChatGPT, Gemini. Free on wp.org.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA modular MCP server that provides access to over 2,000 OPNsense firewall management methods through 88 specialized tools. It enables AI assistants to securely manage firewall rules, network interfaces, and system diagnostics using a type-safe TypeScript interface.96MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to manage OPNsense firewall, interfaces, DHCP, DNS, routes, and services via natural language through 42 MCP tools.1MIT
- AlicenseAqualityDmaintenanceEnables interaction with OPNsense firewalls through MCP tools for managing firewall rules, interfaces, DHCP leases, and system monitoring.26MIT
- AlicenseNot gradedqualityCmaintenanceThis MCP server enables AI agents to inspect and modify an OPNsense firewall via natural language, using a compact set of generic tools and a resource registry to cover 96 CRUD operations.17 npmAGPL 3.0