开源安全-MCP服务器

Name: 开源安全-MCP服务器
Author: Pixelworlds

作者：Pixelworlds17 星标更新：2025-07-06

安装使用来源：spider==github.com

项目介绍

OPNsense MCP 服务器

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

特性

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

MCP服务器作为AI助手（如Claude Desktop）与您的OPNsense防火墙之间的桥梁，通过模块化工具界面提供安全的API访问。

<small>Claude Desktop中的用法</small> OPNsense MCP服务器网络架构

<small>Claude Code中的用法</small> <img width="920" alt="image" src="https://gips2.baidu.com/it/u=3770568054,1318642985&fm=3081&app=3081&f=PNG?w=1840&h=1126" />

安装

作为MCP服务器

此包设计用于与AI助手（如Claude Desktop、Cursor或其他兼容MCP的客户端）一起使用的MCP（模型上下文协议）服务器。

先决条件

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

从npm安装

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

作为MCP服务器的使用

Claude Desktop配置

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %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个插件模块工具，请在args中添加"--plugins"或在env中设置"INCLUDE_PLUGINS": "true"。

测试设置

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

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

解决Claude Desktop设置问题

连接问题：

验证您的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服务器 v0.6.0（模块化）已启动
核心工具：24个模块
插件工具：64个模块（禁用）
总共可用：24个模块

Cursor配置

添加到您的Cursor设置（项目中的.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_manage获取网络接口信息"
"使用plugin_nginx_manage检查Web服务器配置"
"使用diagnostics_manage查看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 Web服务器	`reverseProxySearchDomain`，`serviceStatus`
`plugin_bind_manage`	BIND DNS	`domainSearchDomain`，`recordSearchRecord`
`plugin_acmeclient_manage`	Let's Encrypt	`certificatesSearch`，`certificatesIssue`

从源码构建

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

# 克隆仓库
git clone https://github.com/richard-stovall/opnsense-mcp-server.git
cd opnsense-mcp-server

# 使用Yarn 4.9.2安装依赖
yarn install

# 构建项目
yarn build

# 本地运行
yarn start

开发

开发脚本

yarn generate-tools  # 生成工具定义
yarn build          # 构建服务器
yarn build:all      # 生成工具并构建
yarn dev            # 使用热重载运行
yarn type-check     # 不发出的类型检查
yarn start          # 启动服务器

技术栈

运行时：Node.js，使用tsx执行TypeScript
包管理器：Yarn 4.9.2，带有Plug'n'Play
构建系统：简单的TypeScript编译成单个文件
语言：TypeScript 5.3+
MCP SDK：@modelcontextprotocol/sdk
API客户端：@richard-stovall/opnsense-typescript-client
验证：Zod用于模式验证
测试：Jest，带TypeScript支持

API集成

服务器使用@richard-stovall/opnsense-typescript-client包，该包提供：

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

示例工具实现

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

贡献

欢迎贡献！请随意提交Pull Request。

分叉仓库
创建您的功能分支（git checkout -b feature/AmazingFeature）
提交更改（git commit -m 'Add some AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature）
打开Pull Request

许可证

本项目根据MIT许可证发布 - 查看LICENSE文件了解详情。

致谢

基于Anthropic的Model Context Protocol
由@richard-stovall/opnsense-typescript-client驱动
受OPNsense社区启发

为OPNsense社区制作