内容
# OPNsense MCP/LLM 工具包
使用自然语言配置 OPNsense 防火墙，支持任何与 MCP 兼容的 LLM。
<p align="center">
<img src="docs/images/cover.png" alt="OPNsense 用户指南封面" width="400"/>
</p>
## 这是什么
一个完整的工具包，允许您使用 Claude、Cursor、OpenCode 或其他 LLM 通过对话配置 OPNsense 防火墙。包含增强的 MCP 服务器，带有 WireGuard、PF 状态、网关和别名等附加工具。
```
"创建一个访客 VLAN，允许访问互联网但不允许访问我的 LAN"
"将 443 端口转发到我的 web 服务器（地址：192.168.1.50）"
"显示所有阻止流量的防火墙规则"
"检查 WireGuard 隧道状态"
```
---
## 快速入门
1. **获取 API 凭证**（来源：OPNsense 系统 > 访问 > 用户 > API 密钥）
2. **安装并运行 MCP 服务器**：
```bash
cd opnsense-mcp-server
npm install
npm run build
```
3. **将 MCP 服务器添加到 LLM 客户端配置**：
```json
{
"mcpServers": {
"opnsense": {
"command": "node",
"args": ["/path/to/opnsense-mcp-server/dist/index.js"],
"env": {
"OPNSENSE_HOST": "https://192.168.1.1",
"OPNSENSE_API_KEY": "your_key",
"OPNSENSE_API_SECRET": "your_secret",
"OPNSENSE_VERIFY_SSL": "false"
}
}
}
}
```
4. **将系统提示** 从 `llm/SYSTEM_PROMPT.md` 添加到 LLM 的指令中
5. **开始聊天** - "测试我的 OPNsense 连接"
**完整设置说明：** [SETUP.md](SETUP.md)
---
## 用户指南预览
该工具包包含一份全面的 78 页 PDF 指南，涵盖从初始设置到高级配置的所有内容。
<p align="center">
<img src="docs/images/table-of-contents.png" alt="目录" width="45%"/>
<img src="docs/images/system-requirements.png" alt="系统要求" width="45%"/>
</p>
<p align="center">
<img src="docs/images/firewall-rules.png" alt="防火墙规则文档" width="60%"/>
</p>
<p align="center">
<a href="docs/OPNsense_User_Guide.pdf"><strong>下载完整 PDF 指南</strong></a>
</p>
---
## 包含内容
| 目录/文件 | 用途 |
|----------------|---------|
| `opnsense-mcp-server/` | 增强的 MCP 服务器，包含 WireGuard、PF 状态、网关、别名工具 |
| `llm/SYSTEM_PROMPT.md` | LLM 的复制粘贴提示 |
| `llm/OPNSENSE_KNOWLEDGE.md` | 详细参考（MCP 工具、工作流程、模式） |
| `docs/OPNsense_User_Guide.pdf` | 78 页可读指南 |
| `SETUP.md` | 分步设置说明 |
## MCP 服务器功能
基于基础 opnsense-mcp-server 增强：
- **WireGuard 工具** - 隧道状态、节点管理
- **PF 状态工具** - 查看/清除数据包过滤状态
- **网关工具** - 监控网关状态和故障转移
- **别名工具** - 管理防火墙别名
- **SSH 支持** - 直接 CLI 访问，进行高级操作
---
## 工作原理
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 您 │────>│ LLM │────>│ OPNsense │
│ （自然语言）│ │ （带有 MCP │ │ （防火墙） │
│ │<────│ 工具） │<────│ │
└─────────────┘ └─────────────┘ └─────────────┘
│
MCP 服务器 +
知识库
```
LLM 使用：
- **MCP 工具** 执行 OPNsense 命令（API + SSH）
- **知识文件** 理解 OPNsense 概念和最佳实践
- **系统提示** 遵循安全指南（首先备份，解释更改等）
---
## 要求
- 已启用 API 访问的 OPNsense 防火墙
- 支持 MCP 的 LLM 客户端（Claude Desktop、Cursor、OpenCode、Continue.dev）
- Node.js 18+
## 项目结构
```
OPNsense-MCP-LLM-Toolkit/
├── README.md
├── SETUP.md # 设置说明
├── opnsense-mcp-server/ # 增强的 MCP 服务器
│ ├── src/ # 服务器源代码
│ ├── package.json
│ └── README.md # 服务器特定文档
├── llm/
│ ├── SYSTEM_PROMPT.md # LLM 指令
│ └── OPNSENSE_KNOWLEDGE.md # 参考资料
├── docs/
│ ├── OPNsense_User_Guide.pdf # 完整 PDF 指南
│ └── images/ # 预览图片
└── src/
└── opnsense_user_guide.py # PDF 生成器
```
---
## 许可证
MIT
---
*与 OPNsense 项目无关。OPNsense 是 Deciso B.V. 的商标。*
