Opn Sense MCP

OPNsense MCP 服务器

](https://www.npmjs.com/package/opnsense-mcp-server) 

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

特性

🔥 防火墙管理

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

🌐 NAT配置（基于SSH）

• 出站NAT规则管理
• NAT模式控制（自动/混合/手动/禁用）
• VLAN间流量没有NAT异常规则
• 自动DMZ NAT问题解决
• 直接XML配置操作

🔍 网络诊断

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

🖥️ SSH/CLI执行

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

📊 附加功能

• VLAN管理
• DHCP租约查看和管理
• DNS阻止列表配置
• HAProxy负载均衡器支持
• 配置备份和恢复
• 基础设施即代码支持

安装

先决条件

• Node.js 18+或Bun 1.0+
• OPNsense防火墙（建议使用v24.7+）
• OPNsense的API证书
• SSH访问（可选，用于高级功能）

使用npm快速入门

1. 安装软件包：

npm install -g opnsense-mcp-server

1. 创建一个 .env 使用您的凭据文件：

# Required
OPNSENSE_HOST=https://your-opnsense-host:port
OPNSENSE_API_KEY=your-api-key
OPNSENSE_API_SECRET=your-api-secret
OPNSENSE_VERIFY_SSL=false

# Optional - for SSH features
OPNSENSE_SSH_HOST=your-opnsense-host
OPNSENSE_SSH_USERNAME=root
OPNSENSE_SSH_PASSWORD=your-password
# Or use SSH key
# OPNSENSE_SSH_KEY_PATH=~/.ssh/id_rsa

1. 启动MCP服务器：

opnsense-mcp-server

Bun快速入门（更快）

包子 提供了显著更快的启动时间和更好的性能。

1. 安装Bun（如果尚未安装）：

curl -fsSL https://bun.sh/install | bash

1. 克隆并安装：

git clone https://github.com/vespo92/OPNSenseMCP.git
cd OPNSenseMCP
bun install

1. 创建您的 .env 文件（与上面的npm版本相同）

1. 与Bun一起跑步：

# Development with hot reload
bun run dev:bun

# Production
bun run start:bun

在Claude Desktop中使用Bun

{
  "mcpServers": {
    "opnsense": {
      "command": "bun",
      "args": ["run", "/path/to/OPNSenseMCP/src/index.ts"],
      "env": {
        "OPNSENSE_HOST": "https://your-opnsense:port",
        "OPNSENSE_API_KEY": "your-key",
        "OPNSENSE_API_SECRET": "your-secret",
        "OPNSENSE_VERIFY_SSL": "false"
      }
    }
  }
}

使用Claude Desktop（npm）

添加到您的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问题

// Automatically fix DMZ to LAN routing
await mcp.call('nat_fix_dmz', {
  dmzNetwork: '10.0.6.0/24',
  lanNetwork: '10.0.0.0/24'
});

创建防火墙规则

// Allow NFS from DMZ to NAS
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: 'Allow NFS from DMZ'
});

诊断路由问题

// Run comprehensive routing diagnostics
await mcp.call('routing_diagnostics', {
  sourceNetwork: '10.0.6.0/24',
  destNetwork: '10.0.0.0/24'
});

执行CLI命令

// Run any OPNsense CLI command
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管理
• SSH/CLI执行
• 防火墙规则
• 故障排除

测试

该存储库包括全面的测试实用程序：

# Test NAT functionality
npx tsx scripts/test/test-nat-ssh.ts

# Test firewall rules
npx tsx scripts/test/test-rules.ts

# Test routing diagnostics
npx tsx scripts/test/test-routing.ts

# Run all tests
npm test

发展

从源头构建

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

项目结构

OPNSenseMCP/
├── src/                 # Source code
│   ├── api/            # API client
│   ├── resources/      # Resource implementations
│   └── index.ts        # MCP server entry
├── docs/               # Documentation
├── scripts/            # Utility scripts
│   ├── test/          # Test scripts
│   ├── debug/         # Debug utilities
│   └── fixes/         # Fix scripts
└── dist/               # Build output

故障排除

API身份验证失败

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

SSH连接失败

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

NAT功能不起作用

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

贡献

欢迎投稿！请看 贡献.md 作为指导方针。

许可证

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

支持

• 问题:
• 讨论:
• 文档: 全部文件

致谢

• 专为配合使用而设计 Anthropic的Claude
• 实施 模型上下文协议
• 专为 OPNsense 防火墙

______________________________________________________________________

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