<div align="center">

🌐 EVE-MCP Server

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

Installation · Tools Reference · Configuration · 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:

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:

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

# 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:

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)

{
  "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

SSH Remote Execution (via Netmiko)

Tool	Description
ssh_run_command	SSH into a device and run a single exec-mode command
ssh_run_commands	SSH into a device and run multiple exec-mode commands
ssh_configure	SSH into a device and push configuration commands
remote_command	Run a single command via EVE-NG console
remote_commands	Run multiple commands via EVE-NG console
remote_config	Push config via EVE-NG console
remote_node	Access a node's console session

Supported device types (Netmiko): cisco_ios, cisco_nxos, cisco_xr, arista_eos, juniper_junos, linux, huawei, and many more.

---

🤖 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
│   └── remote_service.py       # Netmiko SSH client
├── utilities/
│   └── sdk_helpers.py          # Shared error-wrapping utilities
├── 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 file for details.

---

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