使用说明

OPNsense MCP 服务器

模块化模型上下文协议（MCP）服务器，提供 88个基于模块的工具 通过类型安全的TypeScript接口访问2000多种OPNsense防火墙管理方法。

特性

模块化架构 -88个逻辑工具（每个模块一个），而不是2000多个单独的工具
API全面覆盖 -访问752个核心方法和1271个插件方法
类型安全 -完全支持TypeScript @richardstoval/onsense打字客户端 v0.5.3
插件支持 -可选支持64个插件模块
智能组织 -按模块分组的相关操作，便于发现

MCP服务器充当人工智能助手（如Claude Desktop）和OPNsense防火墙之间的桥梁，通过模块化工具界面提供安全的API访问。

在Claude Desktop中的使用

Claude代码中的用法

安装

作为MCP服务器

此软件包旨在用作MCP（模型上下文协议）服务器，带有Claude Desktop、Cursor或其他MCP兼容客户端等AI助手。

先决条件

Node.js 18或更高版本
启用API访问的OPNsense防火墙
您的OPNsense安装中的API密钥和秘密

从npm安装

npm install -g @richard-stovall/opnsense-mcp-server

用作MCP服务器

Claude桌面配置

将以下内容添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

替代配置方法

使用命令行参数：

{
  "mcpServers": {
    "opnsense": {
      "command": "node",
      "args": [
        "/path/to/opnsense-mcp-server/index.js",
        "--url",
        "https://YOUR-OPNSENSE-IP",
        "--api-key",
        "YOUR-API-KEY",
        "--api-secret",
        "YOUR-API-SECRET",
        "--no-verify-ssl"
      ]
    }
  }
}

启用插件工具： 要包含所有64个插件模块工具，请添加 "--plugins" 到args或set "INCLUDE_PLUGINS": "true" 在env中。

测试设置

配置后，您可以通过询问Claude来测试连接：

“可用的MCP工具有哪些？”
“使用core_manage获取系统状态”
“使用firewall_manage搜索所有别名”
“使用interfaces_manager列出所有网络接口”

克劳德桌面安装故障排除

连接问题：

验证您的OPNsense API是否已启用
检查API密钥是否具有适当的权限
确保可以从您的计算机访问IP/主机名
对于自签名证书，请使用 --no-verify-ssl 或设置 "OPNSENSE_VERIFY_SSL": "false"

查看服务器日志： 检查Claude Desktop日志，查看MCP服务器是否有任何错误消息。

手动测试： 在使用Claude Desktop之前，您可以手动测试服务器：

node /path/to/opnsense-mcp-server/index.js \
  --url https://YOUR-OPNSENSE-IP \
  --api-key YOUR-API-KEY \
  --api-secret YOUR-API-SECRET \
  --no-verify-ssl

这应该输出：

OPNsense MCP server v0.6.0 (modular) started
Core tools: 24 modules
Plugin tools: 64 modules (disabled)
Total available: 24 modules

光标配置

添加到光标设置(.cursor/mcp.json 在您的项目或 ~/.cursor/mcp.json 全球）：

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["-y", "@richard-stovall/opnsense-mcp-server"],
      "env": {
        "OPNSENSE_URL": "https://192.168.1.1",
        "OPNSENSE_API_KEY": "your-api-key",
        "OPNSENSE_API_SECRET": "your-api-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

配置选项

服务器通过环境变量接受配置：

OPNSENSE_URL -OPNsense主机URL（必需）
OPNSENSE_API_KEY -用于身份验证的API密钥（必需）
OPNSENSE_API_SECRET -用于身份验证的API机密（必需）
INCLUDE_PLUGINS -设置为“true”以启用64个插件模块工具（可选）
OPNSENSE_VERIFY_SSL -设置为“false”以禁用SSL验证（仅限开发）

运作原理

模块化MCP服务器为您的AI助手提供88个基于模块的工具。每个工具代表一个OPNsense模块，并接受 method 参数来指定操作。

工具使用模式：

{
  "tool": "firewall_manage",
  "arguments": {
    "method": "aliasSearchItem",
    "params": {
      "searchPhrase": "web"
    }
  }
}

示例提示：

“使用core_manage检查系统状态”
“使用firewall_manage列出所有防火墙别名”
“使用interfaces_manager获取网络接口信息”
“使用plugin_nginx_manage检查web服务器配置”
“使用diagnostics_manager查看ARP表”

模块化方法使发现相关功能变得容易——所有防火墙操作都在 firewall_manage，所有VPN操作都在各自的模块中(openvpn_manage, ipsec_manage, wireguard_manage).

可用模块工具

核心模块（24个工具）

每个工具都提供对该模块中所有方法的访问：

工具名称	描述	示例方法
`core_manage`	核心系统功能	`backupBackups`, `systemReboot`, `firmwareInfo`
`firewall_manage`	防火墙规则和别名	`aliasSearchItem`, `filterAddRule`, `natSearchRule`
`interfaces_manage`	网络接口	`getInterfaces`, `vlanAddItem`, `setInterface`
`diagnostics_manage`	系统诊断	`interfaceGetArp`, `systemActivityGetActivity`
`auth_manage`	身份验证	`userSearchUser`, `groupSearchGroup`
`firmware_manage`	固件更新	`check`, `update`, `upgrade`, `changelog`
`openvpn_manage`	OpenVPN	`instancesSearch`, `instancesAdd`, `serviceReconfigure`
`ipsec_manage`	IPsec VPN	`tunnelSearchPhase1`, `connectionStatus`
`wireguard_manage`	WireGuard VPN	`serverSearchServer`, `clientSearchClient`
`unbound_manage`	DNS解析器	`hostOverrideSearchItem`, `serviceReconfigure`
`dhcpv4_manage`	DHCP服务器	`searchLease`, `addReservation`

插件模块（启用时有64个工具）

流行的插件模块：

工具名称	描述	示例方法
`plugin_nginx_manage`	Nginx web服务器	`generalGet`, `upstreamSearchUpstream`
`plugin_haproxy_manage`	HAProxy负载均衡器	`serverSearchServer`, `statsGet`
`plugin_caddy_manage`	Caddy网络服务器	`reverseProxySearchDomain`, `serviceStatus`
`plugin_bind_manage`	绑定DNS	`domainSearchDomain`, `recordSearchRecord`
`plugin_acmeclient_manage`	让我们加密	`certificatesSearch`, `certificatesIssue`

从源头构建

如果您想贡献或自定义服务器：

# Clone the repository
git clone https://github.com/richard-stovall/opnsense-mcp-server.git
cd opnsense-mcp-server

# Install dependencies with Yarn 4.9.2
yarn install

# Build the project
yarn build

# Run locally
yarn start

发展

开发脚本

yarn generate-tools  # Generate tool definitions
yarn build          # Build the server
yarn build:all      # Generate tools and build
yarn dev            # Run with hot reload
yarn type-check     # Type check without emitting
yarn start          # Start the server

技术栈

运行时：使用tsx执行TypeScript的Node.js
程序包管理器：带塞式铺网的纱线4.9.2
构建系统：将TypeScript简单编译为单个文件
语言：TypeScript 5.3+
MCP-SDK：@modelcontextprotocol/sdk
API客户端：@richardstoval/onsense打字客户端
验证：Zod用于模式验证
测试：支持TypeScript的Jest

API集成

服务器使用 @richardstoval/onsense打字客户端该套餐提供：

所有API调用的完整类型安全
内置错误处理和重试
支持所有601个OPNsense API端点
基于现代Fetch API的实现

示例工具实现

const response = await client.system.getStatus();
return {
  content: [
    {
      type: 'text',
      text: JSON.stringify(response.data, null, 2),
    },
  ],
};

贡献

欢迎投稿！请随时提交拉取请求。

分叉存储库
创建功能分支(git checkout -b feature/AmazingFeature)
提交您的更改(git commit -m 'Add some AmazingFeature')
推到分支(git push origin feature/AmazingFeature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

建立在模型上下文协议通过Anthropic
由...驱动 @richardstoval/onsense打字客户端
受到OPNsense社区的启发

出于对OPNsense社区的热爱