🌐 EVE-MCP Server

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

Python 3.14+ FastMCP License Platform

Installation · Tools Reference · Configuration · Skills

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:

✅ Check / install Python 3.14
✅ Download source ZIP from GitHub and extract
✅ Create a .venv and install all dependencies
✅ Copy files to %APPDATA%\Local\eve-mcp
✅ 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.

EVE-MCP Server