v0.1.0 Beta | Built for Model Context Protocol

The Universal VM Interface for AI Agents

Give Claude, Cursor, and custom AI agents full autonomy over your virtual machines. Control any OS via ultra-fast serial console or vision-enabled noVNC, with zero guest-side configuration for noVNC connection.

Get Started View on GitHub
20+
Tools Available
100%
Agentless
MCP
Native

Quick Installation

Get up and running in minutes

1

Clone Repository

git clone https://github.com/Andreansx/VibeConsole-MCP.git
cd VibeConsole-MCP
2

Install Dependencies

npm install
3

Build TypeScript

npm run build
4

Configure Environment

cp .env.example .env
# Edit .env with your Proxmox credentials

Serial Console Helper Scripts

Enable Proxmox serial console end-to-end for xterm.js access and headless automation.

enable-serial-host.sh enable-serial-guest.sh
Proxmox host

Set up serial socket + VGA

Configures serial0 (socket) and vga=serial0 on the host. Pass your VMID when running.

curl -fsSL https://raw.githubusercontent.com/Andreansx/VibeConsole-MCP/main/scripts/enable-serial-host.sh | bash -s -- <vmid>
Inside the VM

Enable serial console (systemd)

Adds kernel args and starts serial-getty@ttyS0 for xterm.js serial console access inside the guest.

curl -fsSL https://raw.githubusercontent.com/Andreansx/VibeConsole-MCP/main/scripts/enable-serial-guest.sh | bash
sudo reboot

Requirements

  • Node.js 20+
  • Proxmox VE 8.0+
  • Proxmox user with VM.Console, VM.Audit, and VM.PowerMgmt permissions
  • Network access to Proxmox API (port 8006)

Powerful Features

Everything you need to control VMs through AI agents

Hybrid Access

Seamlessly switch between noVNC for GUI interactions and xterm.js serial console for lightweight, reliable CLI automation.

OCR & Text Analysis

Extract text with precise bounding boxes. Support for regex searching and grid-cell mapping helps AI "read" the screen in real-time.

Grid Overlay System

Injects coordinate grids into screenshots, allowing LLMs to perform precise clicks based on grid references (e.g., "K9") instead of unstable pixel offsets.

Boot State Monitoring

Detect early boot stages (BIOS/GRUB) and wait for specific system states or OS readiness before executing agent tasks.

Proxmox Management

Full control over VM power states, snapshots, and resource monitoring directly through the MCP protocol, with no guest-side agents required.

Agentless Architecture

Works entirely via Proxmox API and WebSockets. Control any VM, from legacy Windows to minimal Linux, without installing any software on the guest.

Available Tools

connect_to_serial Preferred serial console session
send_keys Send keyboard input
start_serial_stream Stream serial output via notifications
connect_to_vm Establish WebSocket connection
disconnect_from_vm Close console connection
disconnect_from_serial Close serial console connection
send_mouse Mouse pointer events
send_serial Raw text to serial console
read_screen Capture screen with grid & OCR
read_serial Read buffered serial output
stop_serial_stream Stop a running serial stream
read_serial_stream Read buffered stream output
wait_serial_stream Wait for new stream output
click_grid Click at grid reference
click_text Find and click text
find_text OCR text search
wait_for_boot Monitor boot progress
wait_for_text Wait for text on screen
get_console_capabilities Check VNC/serial availability
start_vm Start virtual machine
shutdown_vm Shutdown or stop VM
reboot_vm Reboot VM
get_vm_status VM state and resource usage
get_vm_config Fetch VM configuration
list_nodes List Proxmox nodes
list_vms List VMs across cluster
list_snapshots List VM snapshots
create_snapshot Create VM snapshot
delete_snapshot Delete VM snapshot
rollback_snapshot Roll back VM snapshot

MCP Server Configuration

Configure for Claude Desktop, Cursor, or any MCP client - prefer the serial console for speed; fall back to noVNC when GUI pixels matter

Example MCP Configuration

JSON 
{
  "mcpServers": {
    "vibeconsole": {
      "command": "node",
      "args": ["/path/to/VibeConsole-MCP/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "pve",
        "PROXMOX_PORT": "8006",
        "PROXMOX_TOKEN": "vibeconsole@pve!mcp-token",
        "PROXMOX_SECRET": "your-token-secret",
        "DEFAULT_NODE": "pve",
        "DEFAULT_VMID": "108"
      }
    }
  }
}