STARWARCLOUD STARWAR.AI
返回市场
开放感知MCP

开放感知MCP

作者：vespo9226 星标更新：2025-11-23
安装使用来源：spider==github.com

项目介绍

OPNsense MCP 服务器

npm 版本 许可证：MIT

一个用于全面管理 OPNsense 防火墙的模型上下文协议（MCP）服务器。此服务器使像 Claude 这样的AI助手能够直接管理防火墙配置、诊断网络问题并自动化复杂的网络任务。

功能

🔥 防火墙管理

  • 完整的防火墙规则 CRUD 操作
  • 正确处理通过API创建的“自动化规则”
  • 跨VLAN路由配置
  • 批量规则创建与管理
  • 多种回退方法增强持久性

🌐 NAT 配置（基于SSH）

  • 出站NAT规则管理
  • NAT模式控制（自动/混合/手动/禁用）
  • 跨VLAN流量的无NAT例外规则
  • 自动解决DMZ NAT问题
  • 直接XML配置操作

🔍 网络诊断

  • 全面路由分析
  • 带有供应商识别的ARP表检查
  • 接口配置管理
  • 网络连接故障排除
  • 常见问题的自动修复能力

🖥️ SSH/CLI 执行

  • 在OPNsense上直接执行命令
  • 配置文件操作
  • 不可通过API进行的系统级操作
  • 服务管理和重启

📊 其他功能

  • VLAN管理
  • DHCP租约查看与管理
  • DNS黑名单配置
  • 支持HAProxy负载均衡器
  • 配置备份与恢复
  • 支持基础设施即代码

安装

先决条件

  • Node.js 18+ 和 npm
  • OPNsense 防火墙（推荐版本 v24.7+）
  • OPNsense 的API凭证
  • SSH访问（可选，用于高级功能）

快速开始

  1. 安装包：
npm install -g opnsense-mcp-server
  1. 创建包含您的凭证的.env文件：
# 必需
OPNSENSE_HOST=https://your-opnsense-host:port
OPNSENSE_API_KEY=your-api-key
OPNSENSE_API_SECRET=your-api-secret
OPNSENSE_VERIFY_SSL=false

# 可选 - 用于SSH功能
OPNSENSE_SSH_HOST=your-opnsense-host
OPNSENSE_SSH_USERNAME=root
OPNSENSE_SSH_PASSWORD=your-password
# 或使用SSH密钥
# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa
  1. 启动MCP服务器：
opnsense-mcp-server

使用Claude Desktop

添加到您的Claude Desktop配置（claude_desktop_config.json）：

{
  "mcpServers": {
    "opnsense": {
      "command": "npx",
      "args": ["opnsense-mcp-server"],
      "env": {
        "OPNSENSE_HOST": "https://your-opnsense:port",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

常见用例

解决DMZ NAT问题

// 自动修复DMZ到LAN的路由
await mcp.call('nat_fix_dmz', {
  dmzNetwork: '10.0.6.0/24',
  lanNetwork: '10.0.0.0/24'
});

创建防火墙规则

// 允许从DMZ到NAS的NFS
await mcp.call('firewall_create_rule', {
  action: 'pass',
  interface: 'opt8',
  source: '10.0.6.0/24',
  destination: '10.0.0.14/32',
  protocol: 'tcp',
  destination_port: '2049',
  description: '允许从DMZ的NFS'
});

诊断路由问题

// 运行全面的路由诊断
await mcp.call('routing_diagnostics', {
  sourceNetwork: '10.0.6.0/24',
  destNetwork: '10.0.0.0/24'
});

执行CLI命令

// 运行任何OPNsense CLI命令
await mcp.call('system_execute_command', {
  command: 'pfctl -s state | grep 10.0.6'
});

MCP工具参考

该服务器提供了按类别组织的50多种MCP工具：

防火墙工具

  • firewall_list_rules - 列出所有防火墙规则
  • firewall_create_rule - 创建新规则
  • firewall_update_rule - 更新现有规则
  • firewall_delete_rule - 删除规则
  • firewall_apply_changes - 应用待处理更改

NAT工具

  • nat_list_outbound - 列出出站NAT规则
  • nat_set_mode - 设置NAT模式
  • nat_create_outbound_rule - 创建NAT规则
  • nat_fix_dmz - 解决DMZ NAT问题
  • nat_analyze_config - 分析NAT配置

网络工具

  • arp_list - 列出ARP表条目
  • routing_diagnostics - 诊断路由问题
  • routing_fix_all - 自动修复路由问题
  • interface_list - 列出网络接口
  • vlan_create - 创建VLAN

系统工具

  • system_execute_command - 执行CLI命令
  • backup_create - 创建配置备份
  • service_restart - 重启服务

完整的列表，请参阅docs/api/mcp-tools.md。

文档

测试

仓库包括全面的测试工具：

# 测试NAT功能
npx tsx scripts/test/test-nat-ssh.ts

# 测试防火墙规则
npx tsx scripts/test/test-rules.ts

# 测试路由诊断
npx tsx scripts/test/test-routing.ts

# 运行所有测试
npm test

开发

从源码构建

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
npm install
npm run build

项目结构

OPNSenseMCP/
├── src/                 # 源代码
│   ├── api/            # API客户端
│   ├── resources/      # 资源实现
│   └── index.ts        # MCP服务器入口
├── docs/               # 文档
├── scripts/            # 实用脚本
│   ├── test/          # 测试脚本
│   ├── debug/         # 调试工具
│   └── fixes/         # 修复脚本
└── dist/               # 构建输出

故障排除

API认证失败

  • 验证API密钥和秘密是否正确
  • 确保在OPNsense中启用了API访问
  • 检查防火墙规则是否允许API访问

SSH连接失败

  • 验证.env中的SSH凭据
  • 确保在OPNsense中启用了SSH
  • 检查用户是否有适当的权限

NAT功能无法工作

  • NAT管理需要SSH访问
  • 将SSH凭据添加到环境变量中
  • 测试：npx tsx scripts/test/test-nat-ssh.ts

贡献

欢迎贡献！请参阅CONTRIBUTING.md获取指南。

许可证

该项目采用MIT许可证 - 详情请参阅LICENSE文件。

支持

致谢

版本：0.8.2 | 状态：生产就绪 | 最后更新：2025年8月