Opnsense Mcp

OPNsense MCP 服务

用于执行 OPNsense 防火墙操作的 MCP 服务（ARP、DHCP、日志、规则、接口、系统状态、数据包捕获）。

可选择以下两种部署模式之一：

• STDIO（本地）：适合由 Cursor/Claude Code/Continue 直接运行服务进程。
• SSE（集中式）：适合通过 HTTPS 提供共享的长期运行服务。

演示

使用 Claude Code CLI 查询防火墙。实时示例，采用真实网络数据：

项目缘起

以前，为了检查日志或获取 ARP 数据，总要通过 SSH 登录防火墙，很快就让人厌烦了。现在，你可以向 Claude 提问：

• “现在网络上发生了什么？”
• “显示最新的防火墙拦截记录”
• “告诉我这台主机的情况”
• “捕获可疑流量的数据包”

Claude 会通过 MCP 查询防火墙，并一次性提供分析和背景信息。在家庭实验室和企业部署中都同样适用。

快速开始

1) 本地设置（两种模式都必需）

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
cp examples/.env.example ~/.env

编辑 ~/.env：

OPNSENSE_API_KEY=your_api_key
OPNSENSE_API_SECRET=your_api_secret
OPNSENSE_FIREWALL_HOST=your.firewall.host
# HTTP/SSE only; stdio ignores it. Generate with: openssl rand -hex 32
MCP_SECRET_KEY=

2) 选择模式

模式 A：STDIO（本地 IDE/客户端）

配置 MCP 客户端以启动 mcp_start.sh：

{
  "mcpServers": {
    "opnsense-mcp": {
      "command": "/bin/bash",
      "args": ["/absolute/path/to/opnsense-mcp/mcp_start.sh"],
      "cwd": "/absolute/path/to/opnsense-mcp"
    }
  }
}

参见完整指南：docs/GETTING_STARTED.md。

模式 B：SSE（集中式服务）

运行 Linux 安装程序（Podman + quadlet + Caddy TLS）：

sudo bash deploy/install.sh

客户端连接到：

https://<your-hostname>/sse

每个请求都必须发送 Authorization: Bearer <MCP_SECRET_KEY>。如果密钥为空或是占位符，服务将拒绝通过 HTTP 传输启动。

参见部署文档：

• docs/CENTRALIZED_DEPLOY_SPEC.md
• deploy/README.md
• deploy/TLS.md

可用功能

主要工具：

• 发现：arp、dhcp、lldp
• 监控：system、get_logs、packet_capture
• 防火墙规则：fw_rules、mkfw_rule、set_fw_rule、toggle_fw_rule、rmfw_rule
• 接口：interface_list

完整参考：docs/REFERENCE/FUNCTION_REFERENCE.md

最新动态（2026 年 6 月）

最近合并了 5 个 PR。完整详情和使用示例请参见 docs/FEATURES_UPDATE.md。

• Streamable HTTP 传输 — 原生 FastMCP 服务支持 stdio、sse 和 streamable-http（MCP 规范 2025-03-26）。通过 deploy/install.sh 部署。
• DHCP client_id（DUID）支持 — mk_dhcp_host 和 move_dhcp_host 接受可选的 DUID，用于有状态 DHCPv6 匹配。
• Semver 镜像标签 — 主构建会标记为相对于 pyproject.toml 版本的下一个补丁版本预发布版本（1.0.0 之后为 1.0.1-dev.a1b2c3d），或使用发布标签（1.0.0）。
• 容器注册表 — 仅允许固定标签；不接受 :latest。设置 OPNSENSE_MCP_IMAGE_REPO，或使用 --build-local 在本地构建。
• install.sh readonly 修复 — 已解决 install.sh 与 lib.sh 之间 Bash readonly 冲突的问题。

使用场景

• 家庭实验室网络故障排查 — 在终端查询防火墙日志，获取 Claude 对当前情况的分析
• 安全运营 — 自动化事件分诊：“分析最近一小时的拦截记录”
• 基础设施自动化 — 编写可感知 MCP、能够动态查询防火墙状态的脚本
• DevOps 故障排查 — 无需 SSH 会话即可快速检查 VLAN/接口状态

反馈

前 10 位用户的反馈将纳入工具改进。如果你发现错误或有想法，请提交 issue 或讨论帖。

审查时从哪里着手

scripts/risk_map.py 根据 git 历史，按缺陷可能性为源文件排序——变更频率乘以修复密度——让审查者优先查看高风险文件，并可提前结束。它不会查找错误，只会找出错误集中的位置。

python3 scripts/risk_map.py --top 15

CI 会在每个拉取请求中运行此脚本，同时在建议性的 Insights 工作流中生成复杂度报告（radon）并检查安全模式（bandit）。此工作流不会阻止合并。待确认这些数据可信后，才会加入会阻止构建的阈值。

文档索引

• 从这里开始：docs/GETTING_STARTED.md
• Claude Code 相关说明：docs/CLAUDE_CODE_INTEGRATION.md
• 集中式 SSE 规范：docs/CENTRALIZED_DEPLOY_SPEC.md
• 贡献者指南：docs/DEVELOPMENT/CONTRIBUTING.md
• 品牌资源：docs/assets/

许可证

本项目根据 MIT License 发布。