快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

docker run --rm opnsense-mcp:dev pytest

详细介绍

opensense-mcp

独立MCP服务器，用于从任何MCP客户端管理OPNsense Core API工作流。

快速开始

第一阶段是大多数用户的默认路径：

拉取已发布的Docker镜像
引导私有本地状态仓库
将MCP作为本地Docker化stdio服务器运行
将私有本地状态回购装入 /workspace
从同一台机器上的Codex或Cursor连接
在考虑任何远程部署之前，在本地验证OPNsense工作流

阶段2添加了用于家庭实验室或集群使用的私有HTTPS远程托管。

对于大多数用户来说，从终端用户快速入门开始：

docs/end-user-quickstart.md

默认引导值：

回购路径： ~/dev/opnsense
Codex MCP服务器名称： opnsense
基本URL示例： http://opnsense.internal

如果您正在测试或想要一个隔离的工作区，请将其覆盖为以下内容 opnsense-uat.

它做什么

公开结构化MCP工具，用于发现、规划、应用、验证、快照和回滚
直接使用官方OPNsense核心API
将历史记录和XML快照写入已挂载的私有状态仓库
仅在验证成功后创建git提交

第一阶段运行时模型

已发布的服务器映像保持通用。特定于路由器的状态存在于单独的挂载工作区中。

将您的私有路由器状态仓库装载到以下位置的容器中 /workspace
通过环境变量提供OPNsense API凭据
从MCP客户端通过stdio运行服务器
在UAT期间，将状态仓库保存在工作站本地

第二阶段运行时模型

第二阶段是在家庭实验室或类似的永远在线环境中进行私有远程托管的高级部署。

通过Streamable HTTP运行相同的MCP服务器
在HTTPS后私下托管
保持相同的挂载工作区和历史/快照契约
不要将此视为默认的入职路径

配置

所需的环境变量：

OPNSENSE_BASE_URL
OPNSENSE_API_KEY
OPNSENSE_API_SECRET

可选环境变量：

OPNSENSE_VERIFY_TLS 默认 true
OPNSENSE_ALLOW_INSECURE_HTTP 默认 false
OPNSENSE_WORKSPACE_PATH 默认 /workspace
OPNSENSE_SNAPSHOT_HOST 默认 this
OPNSENSE_GIT_AUTHOR_NAME
OPNSENSE_GIT_AUTHOR_EMAIL
OPNSENSE_MCP_TRANSPORT 默认 stdio
OPNSENSE_MCP_HTTP_HOST 默认 127.0.0.1
OPNSENSE_MCP_HTTP_PORT 默认 8000
OPNSENSE_MCP_HTTP_PATH 默认 /mcp
OPNSENSE_MCP_IMAGE_REF

安全默认值：

默认情况下允许HTTPS
普通HTTP被拒绝，除非 OPNSENSE_ALLOW_INSECURE_HTTP=true
发布的运行时映像不包括本地映像 .env 文件或测试夹具
默认情况下，运行时映像以非root用户身份运行

私人国家回购布局

你挂载的工作区应该是一个私有的git仓库。MCP服务器将创建和更新：

private-router-state/
  history/
    20260323-120000-update-dnsmasq-option-6.md
  snapshots/
    current-config.xml

推荐设置：

mkdir -p ~/dev/opnsense/history
mkdir -p ~/dev/opnsense/snapshots
cd ~/dev/opnsense
git init

或者让引导脚本创建此布局并为您注册Codex。

本地开发

贡献者和源代码构建工作流：

docker build --target dev -t opnsense-mcp:dev .
docker run --rm opnsense-mcp:dev pytest
docker run --rm opnsense-mcp:dev ruff check .
docker run --rm opnsense-mcp:dev ruff format --check .
docker run --rm opnsense-mcp:dev mypy src

发布图像设置

如果您使用的是已发布的版本，请提取最新图像并下载引导脚本：

docker pull ghcr.io/addlockwood/opnsense-mcp:latest
curl -fsSL -o setup-local.sh \
  https://github.com/addlockwood/opnsense-mcp/releases/latest/download/setup-local.sh
chmod +x setup-local.sh
./setup-local.sh

引导脚本将：

询问在哪里创建私有仓库
询问要使用哪个Codex MCP服务器名称
询问路由器连接是否应默认为HTTPS或受信任的本地HTTP
询问要在生成的启动器中固定哪个图像引用
脚手架可写仓库布局
创建本地启动器脚本
可选择在Codex中注册stdio MCP服务器

如果脚本是从标记的GitHub版本下载的，则生成的启动器默认为该图像标签。之后，编辑生成的 .env.local 在您的私人回购中，填写您的OPNsense API值。

从源代码构建

如果你想在本地构建而不是拉取一个版本：

docker build --target runtime -t opnsense-mcp:runtime .
./scripts/setup-local.sh ~/dev/opnsense opnsense opnsense-mcp:runtime

对于正常安装，请接受默认设置。对于测试，请选择不同的仓库和服务器名称，例如 opnsense-uat.

将其作为本地stdio MCP服务器运行：

docker run --rm -i \
  --user "$(id -u):$(id -g)" \
  -e OPNSENSE_BASE_URL=https://router.example \
  -e OPNSENSE_API_KEY=... \
  -e OPNSENSE_API_SECRET=... \
  -e OPNSENSE_VERIFY_TLS=true \
  -e OPNSENSE_MCP_IMAGE_REF=ghcr.io/addlockwood/opnsense-mcp:latest \
  -e HOME=/tmp \
  -v /path/to/private-router-repo:/workspace \
  ghcr.io/addlockwood/opnsense-mcp:latest

对于真正的本地UAT运行，点 /path/to/private-router-repo 在您的私有状态仓库，而不是这个公共项目仓库。

对于仍然使用纯HTTP的受信任的本地实验室，请添加：

-e OPNSENSE_ALLOW_INSECURE_HTTP=true

MCP客户端设置

本地stdio配置文件示例 examples/:

食品法典： examples/codex/config.toml
光标： examples/cursor/mcp.json
Bootstrap脚本： scripts/setup-local.sh
最终用户指南： docs/end-user-quickstart.md
安全注意事项： SECURITY.md

这些示例假设：

Docker镜像在本地可用，可以从已发布的注册表或本地构建中获取
您的本地私有状态仓库已从工作站装载
您的OPNsense API凭据是作为主机上的环境变量提供的

对于大多数用户来说，引导脚本加上已发布的GHCR映像是更容易的路径，因为它自动生成启动器和本地仓库，而不需要源代码签出。

UAT检查表

使用此检查表进行第一阶段验收：

从Codex或Cursor连接到本地Docker stdio服务器。
跑 connectivity_preflight 并确认路由器可达性、身份验证、工作区可写性和快照访问都是健康的。
跑 inspect_runtime 并确认工作空间路径为 /workspace 并映射到您的私有挂载仓库，而不是您的源代码仓库。
跑 inspect_dns_topology, inspect_dhcp，以及 explain_resolution_path 至少一个已知的内部主机名。
确认 capture_dns_diagnosis 写 snapshots/current-config.xml 并在拓扑不一致时返回带有警告的诊断包。
为一个支持的更改生成计划，但尚未应用。
确认并应用一个支持的突变。
仅重新配置受影响的OPNsense服务。
通过API读回验证更改后的状态。
确认新的历史记录条目已写入 history/.
确认挂载的私有仓库收到已知良好的git提交。
回滚到上一次提交并验证恢复的状态。

工具概述

list_core_modules
connectivity_preflight
inspect_runtime
inspect_dhcp
inspect_dns_topology
explain_resolution_path
capture_dns_diagnosis
inspect_state
search_records
plan_change
apply_change
reconfigure_services
validate_change
capture_snapshot
rollback_change

备注

V1支持广泛的Core API发现，并为支持的记录类型提供分段写入适配器。如今，已实现的突变适配器包括：

unbound.settings.host_override
dnsmasq.settings.option

其他模块保持可检查和面向计划，直到确认其写入有效载荷。

高级部署

第二阶段部署指南生效 docs/advanced-deployment.md.

这条路是为了：

私有远程HTTP MCP托管
家庭实验室或集群部署
HTTPS入口和部署特定的网络

它有意为本地快速启动提供可选功能，但支持私有HTTPS部署。

目录标签

版本控制PythonCursorOPNsense管理本地部署API工具网络配置Docker化工具

支持客户端

Cursor

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

运行时（runtime，运行环境）

Docker

工具数量（toolCount，工具数）

15

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdionone部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

MCP World

mcpworld.com

/detail/eda3deea68031d861b92b35833ee6e73

独立MCP服务器，用于从任何MCP客户端管理OPNsense核心API工作流程。支持配置发现、计划、应用、验证、快照和回滚功能，适用于本地测试和远程部署场景。

继续浏览同类 MCP

更多运维云端 MCP（13,854）返回 MCP 目录

上一个 MCP

Opm MCP Server

OpenMOHAA MCP Server 是一个用于自动化、测试和控制 OpenMOHAA 游戏的完整协议服务器，支持游戏生命周期控制、UI自动化、性能监控等功能。

下一个 MCP

Ops Center MCP Server

一个基于FastAPI的CRUD服务器，用于管理租户、标签、任务映射和代理性能。

Opnsense MCP