---

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

🖥️ 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.

---

🤖 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 file for details.

---