eve-mcp

<div align="center"> # 🌐 EVE-MCP Server **An MCP (Model Context Protocol) server that bridges AI assistants with EVE-NG network simulation labs.** [](https://www.python.org/) [](https://github.com/jlowin/fastmcp) [](LICENSE) []() [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>