Skip to main content
Glama
OPNsense MCP Server

OPNsense MCP Server

by lucamarien

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 密钥

  1. 登录您的 OPNsense Web 界面

  2. 前往 系统 > 访问 > 用户

  3. 编辑现有用户或创建专用 API 用户:

    • 对于生产环境,创建一个专用用户(例如 mcp-api),仅授予所需权限

    • 对于只读访问,将该用户分配到具有只读 API 访问权限的组

  4. 向下滚动到 API 密钥 部分,点击 + 按钮

  5. 将生成一对密钥/机密,并下载一个文件(apikey.txt)

  6. 该文件包含两行 — key=your-api-key-here 和 secret=your-api-secret-here

  7. 安全存储这些凭据 — 机密无法再次从 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-mcp CLI 不在你的 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_URL

(必填)

OPNsense API 基础 URL(必须以 /api 结尾)

OPNSENSE_API_KEY

(必填)

来自 OPNsense 用户设置的 API 密钥

OPNSENSE_API_SECRET

(必填)

来自 OPNsense 用户设置的 API 机密

OPNSENSE_VERIFY_SSL

true

验证 SSL 证书(自签名证书使用 false)

OPNSENSE_ALLOW_WRITES

false

启用写操作(防火墙规则、服务控制)

自定义端口: 如果你的 OPNsense Web GUI 运行在非标准端口(例如 10443),请在 URL 中包含它:https://192.168.1.1:10443/api

可用工具(81 个)

系统(7 个工具)

工具

描述

opn_system_status

系统信息,包括固件版本、产品名称和架构

opn_list_services

列出所有服务及其运行状态。参数:search、limit

opn_gateway_status

网关可用性、延迟和 dpinger 健康检查

opn_download_config

下载 config.xml 备份,可选择剥离敏感数据。参数:include_sensitive(默认:false — 密码和密钥会被编辑)

opn_scan_config

扫描完整配置,将其解析为各节,并收集运行时清单(固件、插件、DHCP、DNS、接口、服务)。结果按会话缓存。参数:force

opn_get_config_section

获取特定配置节作为结构化 JSON。参数:section、include_sensitive

opn_mcp_info

MCP 服务器版本、写模式状态、检测到的 OPNsense 版本、API 风格,以及防火墙写入是否仍受保存点/回滚保护

网络(5 个工具)

工具

描述

opn_interface_stats

每个接口的流量统计(字节入/出、数据包、错误)

opn_arp_table

ARP 表,显示 IP 到 MAC 地址的映射

opn_ndp_table

NDP(邻居发现协议)表,显示 IPv6 到 MAC 地址的映射

opn_ipv6_status

所有接口的 IPv6 配置和地址状态(方法、实时地址、摘要)

opn_list_static_routes

已配置的静态路由。参数:search、limit

防火墙(21 个工具)

工具

描述

写入

opn_list_firewall_rules

列出 MVC 防火墙过滤规则。参数:search、limit

否

opn_list_firewall_aliases

列出别名定义(IP 列表、端口组、GeoIP、URL)。参数:search、limit

否

opn_list_nat_rules

列出 NAT 端口转发(DNAT)规则。参数:search、limit

否

opn_list_firewall_categories

列出防火墙规则类别及其 UUID。参数:search、limit

否

opn_firewall_log

最近的防火墙日志条目,支持客户端过滤。参数:source_ip、destination_ip、action、interface、limit

否

opn_confirm_changes

确认待定的更改,取消 60 秒自动回滚(OPNsense < 26.7;在 26.7+ 上为无操作,返回 not_applicable)。参数:revision

是

opn_toggle_firewall_rule

使用保存点切换规则的启用/禁用状态(OPNsense < 26.7)。参数:uuid

是

opn_add_firewall_rule

使用保存点创建新的过滤规则(OPNsense < 26.7)。参数:action、direction、interface、ip_protocol、protocol、source_net、destination_net、destination_port、description

是

opn_delete_firewall_rule

使用保存点按 UUID 删除过滤规则(OPNsense < 26.7)。参数:uuid

是

opn_add_alias

创建新的别名。参数:name、alias_type、content、description

是

opn_add_nat_rule

使用保存点创建 NAT 端口转发规则(OPNsense < 26.7)。参数:destination_port、target_ip、interface、protocol、target_port、description

是

opn_add_firewall_category

创建新的防火墙规则类别。参数:name、color

是

opn_delete_firewall_category

使用保存点按 UUID 删除防火墙规则类别(OPNsense < 26.7)。参数:uuid

是

opn_set_rule_categories

使用保存点为防火墙规则分配类别(OPNsense < 26.7)。参数:uuid、categories

是

opn_add_icmpv6_rules

根据 RFC 4890 创建 IPv6 运行所需的必要 ICMPv6 规则(NDP、RA、ping6)。参数:interface

是

opn_update_alias

更新现有别名(name、content、type、description)。读-改-写。参数:uuid、name、content、description、alias_type、enabled

是

opn_delete_alias

按 UUID 删除别名。先检查规则引用。参数:uuid

是

opn_toggle_alias

切换别名的启用/禁用状态。参数:uuid

是

opn_update_firewall_rule

使用保存点更新过滤规则字段(OPNsense < 26.7)。参数:uuid、action、direction、interface、ip_protocol、protocol、source_net、source_not、source_port、destination_net、destination_not、destination_port、gateway、log、quick、sequence、categories、description、enabled

是

opn_update_nat_rule

使用保存点更新 NAT 端口转发规则(OPNsense < 26.7)。参数:uuid、interface、protocol、destination_port、target_ip、target_port、description、enabled

是

opn_delete_nat_rule

使用保存点按 UUID 删除 NAT 端口转发规则(OPNsense < 26.7)。参数:uuid

是

注意: 保存点保护仅存在于 OPNsense < 26.7。在 26.7+ 上,这些工具会立即且永久地应用更改——请参阅写入操作与保存点。

DNS(13 个工具)

工具

描述

写入

opn_list_dns_overrides

Unbound 主机覆盖(本地 DNS 记录)。参数:search、limit

否

opn_list_dns_forwards

DNS 转发域(特定域服务器)。参数:search、limit

否

opn_dns_stats

Unbound 解析器统计(查询、缓存命中、运行时间)

否

opn_reconfigure_unbound

应用待定的 DNS 解析器配置更改

是

opn_add_dns_override

添加 Unbound DNS 主机覆盖(A/AAAA 记录)并立即应用。参数:hostname、domain、server、description

是

opn_list_dnsbl

列出 DNSBL 黑名单配置,包含提供商和状态。参数:search、limit

否

opn_get_dnsbl

按 UUID 获取完整的 DNSBL 配置(提供商、允许列表、设置)。参数:uuid

否

opn_set_dnsbl

更新 DNSBL 设置(读-改-写)。参数:uuid、enabled、providers、allowlists、blocklists、wildcards 等

是

opn_add_dnsbl_allowlist

将域名添加到 DNSBL 允许列表而不覆盖。参数:uuid、domains

是

opn_remove_dnsbl_allowlist

从 DNSBL 允许列表中移除域名。参数:uuid、domains

是

opn_update_dnsbl

重新加载 DNSBL 黑名单文件并重启 Unbound(无配置更改,恢复工具)

是

opn_update_dns_override

更新 Unbound DNS 主机覆盖并立即应用。参数:uuid、hostname、domain、server、description、enabled

是

opn_delete_dns_override

删除 Unbound DNS 主机覆盖并立即应用。参数:uuid

是

DHCP(8 个工具)

工具

描述

写入

opn_list_dhcp_leases

来自 ISC DHCP 服务器的活动 DHCPv4 租约

否

opn_list_kea_leases

来自 Kea DHCP 服务器的 DHCPv4 租约。参数:search、limit

否

opn_list_dnsmasq_leases

来自 dnsmasq DNS/DHCP 服务器的 DHCPv4 和 DHCPv6 租约。参数:search、limit

否

opn_list_dnsmasq_ranges

已配置的 DHCP 地址范围(包括带 RA 配置的 DHCPv4 和 DHCPv6)。参数:search、limit

否

opn_add_dnsmasq_range

创建新的 DHCP 范围(IPv4 或带路由器通告配置的 IPv6)。参数:interface、start_addr、end_addr、prefix_len、ra_mode、lease_time、description

是

opn_reconfigure_dnsmasq

应用待处理的 dnsmasq DNS/DHCP 配置更改

是

opn_update_dnsmasq_range

更新 DHCP 范围(地址、租约时间、RA 配置)并应用。参数:uuid、interface、start_addr、end_addr、prefix_len、ra_mode、lease_time、description、enabled

是

opn_delete_dnsmasq_range

按 UUID 删除 DHCP 范围并应用。参数:uuid

是

VPN(3 个工具)

工具

描述

opn_wireguard_status

WireGuard 隧道和对等体状态(需要 os-wireguard 插件)

opn_ipsec_status

IPsec VPN 隧道状态 — IKE(阶段 1)和 ESP/AH(阶段 2)会话

opn_openvpn_status

OpenVPN 连接状态 — 实例、会话和路由

HAProxy(8 个工具)

HAProxy 负载均衡器的完整配置管理(需要 os-haproxy 插件)。

工具

描述

写入

opn_haproxy_status

HAProxy 服务状态和后端健康检查

否

opn_haproxy_search

按类型搜索 HAProxy 资源。参数:resource_type(frontends/backends/servers/actions/acls/healthchecks/errorfiles/resolvers/mailers)、search、limit

否

opn_haproxy_get

获取特定资源的详细配置。参数:resource_type、uuid

否

opn_haproxy_configtest

在应用前验证 HAProxy 配置语法

否

opn_haproxy_add

创建新的 HAProxy 资源。参数:resource_type、config(字段值字典)

是

opn_haproxy_update

更新现有 HAProxy 资源(部分更新)。参数:resource_type、uuid、config

是

opn_haproxy_delete

按 UUID 删除 HAProxy 资源。参数:resource_type、uuid

是

opn_reconfigure_haproxy

应用待处理的 HAProxy 配置更改

是

注意: HAProxy 更改不使用保存点保护 — 它们在重新配置时立即生效。始终在 opn_reconfigure_haproxy 之前调用 opn_haproxy_configtest。

服务(11 个工具)

工具

描述

写入

opn_list_acme_certs

ACME/Let's Encrypt 证书及其状态。参数:search、limit

否

opn_list_cron_jobs

计划中的 cron 作业。参数:search、limit

否

opn_crowdsec_status

CrowdSec 安全引擎状态和活动决策

否

opn_crowdsec_alerts

CrowdSec 安全警报(检测到的威胁)。参数:search、limit

否

opn_list_ddns_accounts

动态 DNS 账户及其更新状态。参数:search、limit

否

opn_add_ddns_account

创建新的动态 DNS 账户。参数:service、hostname、username、password、checkip、interface、description

是

opn_reconfigure_ddclient

应用待处理的动态 DNS 配置更改

是

opn_update_ddns_account

更新动态 DNS 账户(密码为只写)。参数:uuid、service、hostname、username、password、checkip、interface、description、enabled

是

opn_delete_ddns_account

按 UUID 删除动态 DNS 账户。参数:uuid

是

opn_mdns_repeater_status

mDNS Repeater 状态和配置(已启用、接口、阻止列表)。需要 os-mdns-repeater 插件

否

opn_configure_mdns_repeater

配置 mDNS Repeater 以实现跨 VLAN 设备发现(HomeKit、Chromecast、AirPlay)。参数:enabled、interfaces

是

诊断(4 个工具)

工具

描述

opn_ping

从防火墙 ping 主机以测试连通性。参数:host、count(1-10,默认 3)

opn_traceroute

追踪到目的地的网络路径。参数:host、protocol(ICMP/UDP/TCP)、ip_version(4/6)

opn_dns_lookup

从防火墙进行 DNS 查询。参数:hostname、server(可选的自定义 DNS 服务器)

opn_pf_states

查询活动的 PF 状态表。参数:search、limit(最大 1000)

安全(1 个工具)

工具

描述

opn_security_audit

全面的 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 的保存点机制进行:

  1. 在任何防火墙更改之前,自动创建保存点

  2. 应用更改(规则切换、添加或删除)

  3. 60 秒倒计时开始 — 如果未确认,OPNsense 自动还原更改

  4. 使用 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 迁移工作流程

  1. 手动(GUI): 配置 WAN IPv6(来自 ISP 的 DHCPv6-PD 或静态)

  2. 手动(GUI): 配置 LAN 接口(用于前缀委派的跟踪接口模式)

  3. MCP: 通过 opn_add_dnsmasq_range 配置路由器通告,并设置 RA 标志

  4. MCP: 创建 IPv6 防火墙规则(必须允许 ICMPv6 以支持 NDP/RA/PMTUD)

  5. MCP: 通过 opn_add_dns_override 添加 IPv6 DNS 记录

  6. MCP: 配置使用 IPv6 checkip 方法的动态 DNS

  7. MCP: 向 HAProxy 前端添加 IPv6 绑定地址

  8. 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

最佳实践

针对常见防火墙配置任务的领域特定指南:

这些指南展示了真实的 MCP 工具使用模式,并解释了每种方法背后的安全考虑。

贡献

有关详细指南,请参阅 CONTRIBUTING.md。要点:

  1. 所有测试必须使用模拟的 API 响应——切勿连接到真实的 OPNsense

  2. 工具不得重叠——每个工具必须有明确的用途

  3. 编写清晰的文档字符串——它们是 AI 选择工具的唯一指南

  4. 返回结构化数据(字典),而不是格式化字符串

  5. 提交前运行 make validate

许可证

MIT

Available Tools

81 tools
opn_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:

  1. NDP Neighbor Solicitation (link-local -> multicast)

  2. NDP Neighbor Advertisement (link-local -> any)

  3. NDP Router Solicitation (link-local -> all-routers multicast)

  4. NDP Router Advertisement (link-local -> all-nodes multicast)

  5. 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_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

    A3.6/5.0

    Scored across 81 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      96
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      This 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 npm
      AGPL 3.0