🔧 hyperv-mcp

中文

Local MCP server for controlled Hyper-V VM operations. It uses PowerShell Direct, so guest networking and WinRM are not required.

📋 Requirements

• Windows 10/11 Pro, Enterprise, or Education

• Hyper-V enabled

• Python 3.11 or later available as python.exe

• A Windows guest VM and an administrator account for PowerShell Direct

⚙️ Installation

Run PowerShell as Administrator:

git clone https://github.com/Exploo0Osion/hyperv-mcp.git
cd hyperv-mcp
Copy-Item .\config.json.template .\config.json

Edit config.json:

{
  "vm_name": "WINPWN",
  "guest_username": "Administrator",
  "guest_password": "your_guest_password",
  "baseline_snapshot": "BASELINE"
}

Install and start the Windows service:

.\install.ps1

The script installs the Python dependencies, registers the service, and starts it automatically. It uses the current terminal's python.exe and does not create a virtual environment.

During installation, it creates the dedicated local service account HyperVLabSvc, adds it to Hyper-V Administrators, grants it the service logon right, and runs the Windows service under this account.

To uninstall:

.\install.ps1 -Uninstall

🔌 MCP Configuration

Add this Streamable HTTP configuration to your MCP client:

{
  "mcpServers": {
    "hyperv-mcp": {
      "url": "http://127.0.0.1:18745/mcp"
    }
  }
}

The server listens at http://127.0.0.1:18745/mcp. No command, Python path, or manually started MCP process is required.

🛠️ Tools

Guest and host file paths must be absolute. All operations target the VM configured in config.json.

🛡️ Safety Limits

• The service only listens on 127.0.0.1.

• Operations for the single VM are serialized.

• The configured baseline_snapshot cannot be overwritten or deleted.

• Host transfers reject C:\Windows, C:\Program Files, C:\Program Files (x86), and C:\ProgramData.