内容
<div align="center">
# 🌐 EVE-MCP 服务器
**一款连接 AI 助手与 EVE-NG 网络模拟实验室的 MCP（模型上下文协议）服务器。**
[](https://www.python.org/)
[](https://github.com/jlowin/fastmcp)
[](LICENSE)
[]()
[安装](#-installation) · [工具参考](#-tools-reference) · [配置](#-configuration) · [技能](#-ai-agent-skills)
</div>
---
## 概述
**EVE-MCP 服务器** 将整个 EVE-NG REST API 和 SSH 设备访问权限暴露为 MCP 工具，允许 AI 代理（Claude、Antigravity IDE、Antigravity CLI）自主管理网络实验室、配置设备和运行诊断 —— 所有这些都可以通过自然语言完成。
```
AI 代理（Claude / Antigravity）
│
│ MCP 协议（stdio）
▼
┌─────────────┐ REST API ┌──────────────┐
│ EVE-MCP │ ──────────────────▶ │ EVE-NG │
│ 服务器 │ │ 服务器 │
│ │ SSH/Netmiko │ │
│ │ ──────────────────▶ │ 实验室设备 │
└─────────────┘ └──────────────┘
```
### 主要功能
- 🔌 **50+ MCP 工具** — 完整的 EVE-NG 生命周期：会话、实验室、节点、网络、拓扑、配置
- 🖥️ **SSH 远程执行** — 通过 Netmiko（Cisco IOS/NX-OS/XR、Arista、Juniper 等）运行显示命令和推送配置
- 📦 **一键安装** — 互联网安装程序引导 Python 3.14、venv 和所有依赖项
- 🤖 **AI 代理技能** — 捆绑技能教您的 AI 代理 EVE-NG 工作流程开箱即用
- ⚙️ **多平台** — 一步配置 Antigravity IDE、Antigravity CLI 和 Claude Desktop
---
## 🚀 安装
### 选项 1 — 一键互联网安装程序（推荐）
打开 PowerShell 并运行：
```powershell
irm https://trongthoaivn.github.io/eve-mcp/ | iex
```
安装程序将：
1. ✅ 检查/安装 **Python 3.14**
2. ✅ 从 GitHub 下载源 ZIP 并提取
3. ✅ 创建 `.venv` 并安装所有依赖项
4. ✅ 将文件复制到 `%APPDATA%\Local\eve-mcp`
5. ✅ 询问要配置的 AI 平台并写入 `mcp_config.json`
> **注意：** 如果 PowerShell 阻止脚本执行，请运行：
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
> irm https://raw.githubusercontent.com/trongthoaivn/eve-mcp/main/startup.ps1 | iex
> ```
---
### 选项 2 — 手动安装（从源代码）
**先决条件：** Python 3.10+，Git
```bash
# 1. 克隆仓库
git clone https://github.com/trongthoaivn/eve-mcp.git
cd eve-mcp
# 2. 构建 — 创建 .venv 并安装依赖项
build.bat
# 3. 安装 — 复制到 AppData 并配置 AI 平台
install.bat
```
---
## ⚙️ 配置
在项目根目录（或 `%APPDATA%\Local\eve-mcp\`）中创建一个 `.env` 文件，其中包含您的 EVE-NG 凭证：
```ini
EVE_HOST=192.168.1.100
EVE_USERNAME=admin
EVE_PASSWORD=eve
EVE_PROTOCOL=http
EVE_SSL_VERIFY=false
EVE_DISABLE_INSECURE_WARNINGS=true
```
### MCP 配置（由安装程序自动生成）
```json
{
"mcpServers": {
"eve-mcp": {
"command": "C:/Users/<you>/AppData/Local/eve-mcp/.venv/Scripts/python.exe",
"args": ["C:/Users/<you>/AppData/Local/eve-mcp/server.py"],
"env": {
"EVE_HOST": "192.168.1.100",
"EVE_USERNAME": "admin",
"EVE_PASSWORD": "eve",
"EVE_PROTOCOL": "http",
"EVE_SSL_VERIFY": "false",
"EVE_DISABLE_INSECURE_WARNINGS": "true"
}
}
}
}
```
每个平台的配置文件位置：
| 平台 | 配置文件 |
|---|---|
| Antigravity IDE | `%USERPROFILE%\.gemini\config\mcp_config.json` |
| Antigravity CLI | `%USERPROFILE%\.gemini\antigravity-cli\mcp_config.json` |
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
---
## 🛠 工具参考
### 会话管理
| 工具 | 描述 |
|---|---|
| `login` | 认证 EVE-NG 并存储会话 cookie |
| `logout` | 使当前会话失效 |
| `reset_session` | 清除内存和磁盘上的会话数据 |
### 系统和模板
| 工具 | 描述 |
|---|---|
| `get_server_status` | 返回 EVE-NG 服务器版本和状态 |
| `list_node_templates` | 列出所有可用的节点/设备模板 |
| `node_template_detail` | 获取特定模板的详细信息 |
### 用户管理
| 工具 | 描述 |
|---|---|
| `list_users` | 列出所有 EVE-NG 用户 |
| `list_user_roles` | 列出可用的用户角色 |
| `get_user` | 获取特定用户的详细信息 |
| `add_user` | 创建新用户 |
| `edit_user` | 修改现有用户 |
| `delete_user` | 删除用户 |
### 文件夹和实验室管理
| 工具 | 描述 |
|---|---|
| `list_folders` | 列出 EVE-NG 文件系统中的文件夹 |
| `get_folder` | 获取特定文件夹的内容 |
| `get_lab` | 检索实验室详细信息 |
| `create_lab` | 创建新实验室 |
| `edit_lab` | 修改实验室元数据 |
| `delete_lab` | 删除实验室 |
| `close_lab` | 关闭开放的实验室 |
| `lock_lab` / `unlock_lab` | 锁定或解锁实验室以进行编辑 |
| `export_lab` | 将实验室导出为 `.unl` 文件 |
| `import_lab` | 将 `.unl` 文件导入 EVE-NG |
| `get_lab_topology` | 检索完整的拓扑结构（节点 + 链接） |
| `export_all_nodes` | 导出实验室中所有节点的配置 |
| `get_lab_pictures` | 列出拓扑图图像 |
| `get_lab_picture_details` | 获取特定图片的详细信息 |
### 实验室网络
| 工具 | 描述 |
|---|---|
| `list_networks` | 列出系统中的所有网络 |
| `list_lab_networks` | 列出实验室中的网络 |
| `get_lab_network` | 通过 ID 获取特定实验室网络 |
| `get_lab_network_by_name` | 通过名称获取实验室网络 |
| `add_lab_network` | 向实验室添加新网络 |
| `edit_lab_network` | 修改实验室网络 |
| `list_lab_links` | 列出实验室中的所有链接 |
### 节点管理
| 工具 | 描述 |
|---|---|
| `list_nodes` | 列出实验室中的所有节点 |
| `get_node` | 通过 ID 获取节点详细信息 |
| `get_node_by_name` | 通过名称获取节点详细信息 |
| `add_node` | 向实验室添加新节点 |
| `delete_node` | 从实验室中删除节点 |
| `start_node` / `stop_node` | 打开或关闭节点的电源 |
| `start_all_nodes` / `stop_all_nodes` | 批量打开/关闭电源 |
| `wipe_node` / `wipe_all_nodes` | 将节点重置为出厂状态 |
| `export_node` | 导出节点的运行配置 |
| `enable_node_config` | 在节点上启用配置持久性 |
| `get_node_interfaces` | 列出节点的所有接口 |
| `get_node_configs` | 列出节点的所有保存配置 |
| `get_node_config_by_id` | 检索特定的保存配置 |
| `upload_node_config` | 将启动配置推送到节点 |
### 连接性
| 工具 | 描述 |
|---|---|
| `connect_node` | 将节点接口连接到网络 |
| `connect_node_to_cloud` | 将节点接口桥接到云/网桥 |
| `connect_node_to_node` | 在两个节点之间创建链接 |
| `connect_p2p_interface` | 配置点到点接口 |
### 🖥️ 异步远程命令和配置（基于作业）
所有命令执行和配置工具现在都使用后台作业管理器异步操作。 这些工具会将请求排队并立即返回 `job_id`。
#### 1. 设备 SSH 工具（通过 Netmiko）
| 工具 | 描述 |
|---|---|
| `ssh_run_command` | SSH 进入设备并运行单个执行模式命令（异步） |
| `ssh_run_commands` | SSH 进入设备并运行多个执行模式命令（异步） |
| `ssh_configure` | SSH 进入设备并推送配置命令（异步） |
#### 2. EVE-NG 控制台重定向工具
这些工具连接到设备控制台端口（使用通过 EVE-NG 重定向的 Telnet/VNC），以配置设备或在 SSH 尚未设置时运行命令。
| 工具 | 描述 |
|---|---|
| `remote_command` | 通过 EVE-NG 控制台端口在设备上运行单个命令（异步） |
| `remote_commands` | 通过 EVE-NG 控制台端口在设备上运行多个命令（异步） |
| `remote_config` | 通过 EVE-NG 控制台端口将配置命令推送到设备（异步） |
| `remote_node` | 用于在特定节点上执行命令/配置的通用控制台管理器（异步） |
#### 3. 初始配置对话框绕过
用于在新启动的设备上自动关闭初始配置对话框（“您是否要输入...”）的工具。
| 工具 | 描述 |
|---|---|
| `ssh_bypass_console_dialog` | 通过原始 TCP 套接字连接到设备控制台并关闭设置向导（同步） |
| `ssh_bypass_and_run_command` | 绕过初始对话框，等待启动并运行单个命令（异步） |
| `ssh_bypass_and_run_commands` | 绕过初始对话框，等待启动并运行多个命令（异步） |
| `ssh_bypass_and_configure` | 绕过初始对话框，等待启动并推送配置命令（异步） |
#### 4. 作业管理
使用这些工具轮询进度并检索上述任何异步工具的结果：
| 工具 | 描述 |
|---|---|
| `ssh_job_status` | 轮询作业状态、执行进度和错误消息 |
| `ssh_job_result` | 检索已完成的作业的结果（读取一次，从内存中删除作业） |
| `ssh_cancel_job` | 取消正在运行的后台作业并释放主机并发锁 |
**支持的设备类型** （Netmiko）：`cisco_ios`、`cisco_nxos`、`cisco_xr`、`arista_eos`、`juniper_junos`、`linux`、`huawei` 和 [更多](https://github.com/ktbyers/netmiko#supported-platforms)。
---
## 🤖 AI 代理技能
`skills/` 目录包含预建的技能包，在安装过程中会自动复制到 AI 代理的配置中，教导代理 EVE-NG 工作流程：
| 技能 | 描述 |
|---|---|
| `eve-authentication` | 自动登录，带有会话回退 |
| `eve-lab-implementation` | 生成 UNL 拓扑文件并导入实验室 |
| `eve-lab-management` | 完整的实验室生命周期（创建、导出、导入、删除） |
| `eve-network-connectivity` | 添加网络、连接节点、配置 P2P 链接 |
| `eve-node-management` | 添加、启动、停止、擦除、配置节点 |
| `eve-remote-execution` | SSH 配置和命令执行 |
| `eve-user-system-admin` | 用户和系统管理 |
| `cisco-ios-patterns` | Cisco IOS/IOS-XE 语法和最佳实践 |
| `network-interface-health` | 诊断接口错误（CRC、丢包、波动） |
---
## 📦 项目结构
```
eve-mcp/
├── server.py # FastMCP 入口点
├── controllers/
│ ├── eve_ng_controller.py # EVE-NG MCP 工具注册
│ └── remote_controller.py # SSH/Netmiko MCP 工具注册
├── services/
│ ├── eve_ng_service.py # EVE-NG REST API 客户端
│ ├── job_manager_service.py # 异步 SSH/控制台任务的后台作业管理器
│ └── remote_service.py # Netmiko SSH 客户端
├── utilities/
│ ├── sdk_helpers.py # 共享错误包装实用程序
│ └── logging_decorator.py # 可重用的日志记录装饰器，带有密码掩码
├── skills/ # AI 代理技能包
├── configure_mcp.py # MCP 配置写入器（由安装程序使用）
├── build.bat # 构建脚本（venv + 依赖项）
├── install.bat # 平台安装脚本
├── startup.ps1 # 一键互联网安装程序
├── requirements.txt # Python 依赖项
└── .env # EVE-NG 凭证（不提交）
```
---
## 📋 要求
| 组件 | 版本 |
|---|---|
| Python | 3.10+（推荐 3.14） |
| FastMCP | 3.4.2 |
| httpx | 0.28.1 |
| eve-ng | 0.2.7 |
| python-dotenv | 1.2.2 |
| netmiko | 4.4.0 |
---
## 📄 许可证
该项目根据 **Apache License 2.0** 许可 — 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
---
<div align="center">
由 ❤️ 为网络工程师和 AI 爱好者制作
</div>
