内容
**中文** | [繁體中文](README.zh-TW.md)
# FortiGate MCP 设置适用于 Claude Desktop
直接从 Claude Desktop 使用自然语言管理和查询您的 FortiGate 防火墙，通过 [模型上下文协议（MCP）](https://modelcontextprotocol.io)。
本项目是一个 **配置模板和设置指南**，帮助您快速将 FortiGate MCP 服务器连接到 Claude Desktop（macOS）。
> ⚠️ 此仓库不包含任何真实 IP 地址、API 令牌或其他秘密。每个值都是占位符 — 请按照以下步骤填写您自己的值。
---
## 功能特点
连接后，您可以用自然语言询问 Claude，例如：
- "显示 FortiGate 系统状态"
- "列出所有防火墙策略 — 哪些是允许任意的？"
- "哪些接口正在使用，流量是多少？"
- "运行安全评级检查"
- "VLAN 之间的访问规则是什么？"
底层 MCP 服务器暴露了大约 **94+ 种工具**，涵盖系统监控、防火墙策略、路由、VPN、安全配置文件、无线、交换机、日志等。
---
## 先决条件
| 项目 | 备注 |
|------|-------|
| macOS | 本指南使用 macOS（Windows 路径在下面注明） |
| [Claude Desktop](https://claude.ai/download) | Anthropic 官方桌面应用程序 |
| [Node.js](https://nodejs.org) | 版本 **18 或更高**（使用 `node -v` 验证） |
| FortiGate | FortiOS **7.4 或更高**，具有 REST API 访问权限 |
---
## 安装
### 1. 创建 FortiGate API 令牌
登录到 FortiGate 管理 UI：
```
系统 → 管理员 → 创建新 → REST API 管理员
```
推荐设置：
- **管理员配置文件**：创建 `只读` 配置文件（最小权限）；仅在需要进行更改时暂时提升权限
- **受信任的主机**：输入运行 Claude Desktop 的机器的 IP 地址（例如 `192.168.1.100/32`）以限制 API 源
- 创建后，**复制令牌（仅显示一次！）**
### 2. 安装 MCP 服务器
```bash
# 克隆您选择的 FortiGate MCP 服务器（示例）
git clone https://github.com/<your-fortigate-mcp-repo>.git
cd <fortigate-mcp>
# 安装依赖并构建
npm install
npm run build
# 记下完整路径 — 您需要它来进行配置
pwd
```
### 3. 配置环境变量
复制模板并填写您的详细信息：
```bash
cp .env.example .env
# 在编辑器中打开 .env 并设置您的 FortiGate IP 地址和 API 令牌
```
### 4. 配置 Claude Desktop
将 `mcpServers` 块从 `claude_desktop_config.example.json` 合并到您的 Claude Desktop 配置文件中：
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
> 如果配置文件已经有内容，请仅添加 `mcpServers` 键 — 不要覆盖整个文件。
或运行包含的脚本（它会自动备份现有的配置）：
```bash
./setup.sh
```
### 5. 重启 Claude Desktop
```bash
# macOS
pkill -f "Claude" && sleep 2 && open -a Claude
```
### 6. 验证连接
重启后，在 Claude Desktop 聊天框的左下角点击 **`+` → 连接器**。
您应该看到 `fortigate` 显示为启用（蓝色）。
然后只需输入 "显示 FortiGate 系统状态" 进行测试。
---
## 用法
有关更多自然语言查询示例和工具类别分类，请参见 [docs/USAGE.md](docs/USAGE.md)。
---
## 安全注意事项
- **绝不能** 将 `.env` 或已填写的 `claude_desktop_config.json` 提交到 Git（两者都在 `.gitignore` 中排除）
- 将 API 令牌视为密码 — 如果泄露，请立即在 FortiGate 上撤销并重新生成
- 对于生产环境，请启用 `FORTIGATE_VERIFY_SSL=true` 并使用有效的证书
- 优先使用只读 API 账户以降低意外更改的风险
---
## 故障排除
| 症状 | 可能原因 |
|---------|----------------|
| 连接器未显示 fortigate | Claude 未完全重启（在 macOS 上使用 `Cmd+Q`），JSON 无效或路径错误 |
| 连接但查询失败 | API 令牌或 IP 地址错误，或受信任的主机不包括您的机器 |
| 日志返回为空 | 日志存储在磁盘 / FortiAnalyzer / FortiCloud 上，而不是内存中 |
查看 MCP 连接日志：
```bash
cat ~/Library/Logs/Claude/mcp*.log
```
---
## 许可证
在 MIT 许可证下发布 — 您可以自由修改和使用。
FortiGate 和 FortiOS 是 Fortinet, Inc. 的商标。本项目与 Fortinet 无关联。
