<div align="center">

# 🌐 EVE-MCP Server

**An MCP (Model Context Protocol) server that bridges AI assistants with EVE-NG network simulation labs.**

[![Python 3.14+](https://img.shields.io/badge/python-3.14+-blue.svg)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.4.2-green.svg)](https://github.com/jlowin/fastmcp)
[![License](https://img.shields.io/badge/license-Apache%202.0-orange.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Windows-lightgrey.svg)]()

[Installation](#-installation) · [Tools Reference](#-tools-reference) · [Configuration](#-configuration) · [Skills](#-ai-agent-skills)

</div>

---

## Overview

**EVE-MCP Server** exposes the full EVE-NG REST API and SSH device access as MCP tools, allowing AI agents (Claude, Antigravity IDE, Antigravity CLI) to autonomously manage network labs, configure devices, and run diagnostics — all through natural language.

```
AI Agent (Claude / Antigravity)
        │
        │  MCP Protocol (stdio)
        ▼
  ┌─────────────┐       REST API       ┌──────────────┐
  │ EVE-MCP     │ ──────────────────▶  │  EVE-NG      │
  │ Server      │                      │  Server      │
  │             │       SSH/Netmiko    │              │
  │             │ ──────────────────▶  │  Lab Devices │
  └─────────────┘                      └──────────────┘
```

### Key Features

- 🔌 **50+ MCP Tools** — full EVE-NG lifecycle: sessions, labs, nodes, networks, topology, configs
- 🖥️ **SSH Remote Execution** — run show commands and push configs via Netmiko (Cisco IOS/NX-OS/XR, Arista, Juniper, and more)
- 📦 **One-line Install** — internet installer bootstraps Python 3.14, venv, and all dependencies
- 🤖 **AI Agent Skills** — bundled skills teach your AI agent EVE-NG workflows out of the box
- ⚙️ **Multi-platform** — configures Antigravity IDE, Antigravity CLI, and Claude Desktop in one step

---

## 🚀 Installation

### Option 1 — One-line Internet Installer (Recommended)

Open PowerShell and run:

```powershell
irm https://trongthoaivn.github.io/eve-mcp/ | iex
```

The installer will:
1. ✅ Check / install **Python 3.14**
2. ✅ Download source ZIP from GitHub and extract
3. ✅ Create a `.venv` and install all dependencies
4. ✅ Copy files to `%APPDATA%\Local\eve-mcp`
5. ✅ Ask which AI platforms to configure and write `mcp_config.json`

> **Note:** If PowerShell blocks script execution, run:
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
> irm https://raw.githubusercontent.com/trongthoaivn/eve-mcp/main/startup.ps1 | iex
> ```

---

### Option 2 — Manual Install (from source)

**Prerequisites:** Python 3.10+, Git

```bash
# 1. Clone the repository
git clone https://github.com/trongthoaivn/eve-mcp.git
cd eve-mcp

# 2. Build — creates .venv and installs dependencies
build.bat

# 3. Install — copies to AppData and configures AI platforms
install.bat
```

---

## ⚙️ Configuration

Create a `.env` file in the project root (or in `%APPDATA%\Local\eve-mcp\`) with your EVE-NG credentials:

```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 Config (auto-generated by installer)

```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"
      }
    }
  }
}
```

Config file locations per platform:

| Platform | Config File |
|---|---|
| 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` |

---

## 🛠 Tools Reference

### Session Management

| Tool | Description |
|---|---|
| `login` | Authenticate against EVE-NG and store session cookie |
| `logout` | Invalidate the current session |
| `reset_session` | Clear in-memory and on-disk session data |

### System & Templates

| Tool | Description |
|---|---|
| `get_server_status` | Return EVE-NG server version and status |
| `list_node_templates` | List all available node/device templates |
| `node_template_detail` | Get detailed info for a specific template |

### User Management

| Tool | Description |
|---|---|
| `list_users` | List all EVE-NG users |
| `list_user_roles` | List available user roles |
| `get_user` | Get details for a specific user |
| `add_user` | Create a new user |
| `edit_user` | Modify an existing user |
| `delete_user` | Remove a user |

### Folder & Lab Management

| Tool | Description |
|---|---|
| `list_folders` | List folders in the EVE-NG file system |
| `get_folder` | Get contents of a specific folder |
| `get_lab` | Retrieve lab details |
| `create_lab` | Create a new lab |
| `edit_lab` | Modify lab metadata |
| `delete_lab` | Delete a lab |
| `close_lab` | Close an open lab |
| `lock_lab` / `unlock_lab` | Lock or unlock a lab for editing |
| `export_lab` | Export a lab as a `.unl` file |
| `import_lab` | Import a `.unl` file into EVE-NG |
| `get_lab_topology` | Retrieve the full topology (nodes + links) |
| `export_all_nodes` | Export configs of all nodes in a lab |
| `get_lab_pictures` | List topology diagram images |
| `get_lab_picture_details` | Get details of a specific picture |

### Lab Networks

| Tool | Description |
|---|---|
| `list_networks` | List all networks in the system |
| `list_lab_networks` | List networks within a lab |
| `get_lab_network` | Get a specific lab network by ID |
| `get_lab_network_by_name` | Get a lab network by name |
| `add_lab_network` | Add a new network to a lab |
| `edit_lab_network` | Modify a lab network |
| `list_lab_links` | List all links in a lab |

### Node Management

| Tool | Description |
|---|---|
| `list_nodes` | List all nodes in a lab |
| `get_node` | Get node details by ID |
| `get_node_by_name` | Get node details by name |
| `add_node` | Add a new node to a lab |
| `delete_node` | Remove a node from a lab |
| `start_node` / `stop_node` | Power a node on or off |
| `start_all_nodes` / `stop_all_nodes` | Bulk power on/off |
| `wipe_node` / `wipe_all_nodes` | Reset node(s) to factory state |
| `export_node` | Export a node's running config |
| `enable_node_config` | Enable config persistence on a node |
| `get_node_interfaces` | List all interfaces of a node |
| `get_node_configs` | List all saved node configs |
| `get_node_config_by_id` | Retrieve a specific saved config |
| `upload_node_config` | Push a startup config to a node |

### Connectivity

| Tool | Description |
|---|---|
| `connect_node` | Connect a node interface to a network |
| `connect_node_to_cloud` | Bridge a node interface to a cloud/bridge |
| `connect_node_to_node` | Create a link between two nodes |
| `connect_p2p_interface` | Configure a point-to-point interface |

### 🖥️ Async Remote Command & Configuration (Job-Based)

All command execution and configuration tools now operate **asynchronously** using a background job manager. Instead of blocking the event loop, these tools queue the request and immediately return a `job_id`. 

#### 1. Device SSH Tools (via Netmiko)

| Tool | Description |
|---|---|
| `ssh_run_command` | SSH into a device and run a single exec-mode command (async) |
| `ssh_run_commands` | SSH into a device and run multiple exec-mode commands (async) |
| `ssh_configure` | SSH into a device and push configuration commands (async) |

#### 2. EVE-NG Console Redirection Tools

These tools connect to device console ports (using Telnet/VNC redirected through EVE-NG) to configure devices or run commands when SSH is not yet set up.

| Tool | Description |
|---|---|
| `remote_command` | Run a single command on a device via its EVE-NG console port (async) |
| `remote_commands` | Run multiple commands on a device via its EVE-NG console port (async) |
| `remote_config` | Push configuration commands to a device via its EVE-NG console port (async) |
| `remote_node` | General console manager to execute commands/configs on a specific node (async) |

#### 3. Initial Configuration Dialog Bypass

Tools to automatically dismiss the initial configuration dialog ("Would you like to enter...") on freshly booted devices.

| Tool | Description |
|---|---|
| `ssh_bypass_console_dialog` | Connect to device console via raw TCP socket and dismiss setup wizard (sync) |
| `ssh_bypass_and_run_command` | Bypass initial dialog, wait for boot, and run single command (async) |
| `ssh_bypass_and_run_commands` | Bypass initial dialog, wait for boot, and run multiple commands (async) |
| `ssh_bypass_and_configure` | Bypass initial dialog, wait for boot, and push config commands (async) |

#### 4. Job Management

Use these tools to poll progress and retrieve results for any of the async tools above:

| Tool | Description |
|---|---|
| `ssh_job_status` | Poll job status, execution progress, and error messages |
| `ssh_job_result` | Retrieve results of a completed job (read-once, evicts job from memory) |
| `ssh_cancel_job` | Cancel a running background job and release host concurrency lock |

**Supported device types** (Netmiko): `cisco_ios`, `cisco_nxos`, `cisco_xr`, `arista_eos`, `juniper_junos`, `linux`, `huawei`, and [many more](https://github.com/ktbyers/netmiko#supported-platforms).

---

## 🤖 AI Agent Skills

The `skills/` directory contains pre-built skill packs that are automatically copied to your AI agent's config during installation, teaching the agent EVE-NG workflows:

| Skill | Description |
|---|---|
| `eve-authentication` | Auto-login with session fallback |
| `eve-lab-implementation` | Generate UNL topology files and import labs |
| `eve-lab-management` | Full lab lifecycle (create, export, import, delete) |
| `eve-network-connectivity` | Add networks, connect nodes, configure P2P links |
| `eve-node-management` | Add, start, stop, wipe, configure nodes |
| `eve-remote-execution` | SSH configuration and command execution |
| `eve-user-system-admin` | User and system administration |
| `cisco-ios-patterns` | Cisco IOS/IOS-XE syntax and best practices |
| `network-interface-health` | Diagnose interface errors (CRC, drops, flapping) |

---

## 📦 Project Structure

```
eve-mcp/
├── server.py                   # FastMCP entry point
├── controllers/
│   ├── eve_ng_controller.py    # EVE-NG MCP tool registrations
│   └── remote_controller.py    # SSH/Netmiko MCP tool registrations
├── services/
│   ├── eve_ng_service.py       # EVE-NG REST API client
│   ├── job_manager_service.py  # Background job manager for async SSH/Console tasks
│   └── remote_service.py       # Netmiko SSH client
├── utilities/
│   ├── sdk_helpers.py          # Shared error-wrapping utilities
│   └── logging_decorator.py    # Reusable logging decorator with password masking
├── skills/                     # AI agent skill packs
├── configure_mcp.py            # MCP config writer (used by installers)
├── build.bat                   # Build script (venv + deps)
├── install.bat                 # Platform installer script
├── startup.ps1                 # One-line internet installer
├── requirements.txt            # Python dependencies
└── .env                        # EVE-NG credentials (not committed)
```

---

## 📋 Requirements

| Component | Version |
|---|---|
| Python | 3.10+ (3.14 recommended) |
| FastMCP | 3.4.2 |
| httpx | 0.28.1 |
| eve-ng | 0.2.7 |
| python-dotenv | 1.2.2 |
| netmiko | 4.4.0 |

---

## 📄 License

This project is licensed under the **Apache License 2.0** — see the [LICENSE](LICENSE) file for details.

---

<div align="center">
Made with ❤️ for network engineers and AI enthusiasts
</div>