# 🔧 hyperv-mcp

[中文](README_CN.md)

Local [MCP](https://modelcontextprotocol.io/) 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**:

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

Edit `config.json`:

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

Install and start the Windows service:

```powershell
.\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:

```powershell
.\install.ps1 -Uninstall
```

### 🔌 MCP Configuration

Add this Streamable HTTP configuration to your MCP client:

```json
{
  "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

| Tool     | Description                                     |
| -------- | ----------------------------------------------- |
| `stat` | Query VM status                                 |
| `save` | Create a checkpoint                             |
| `load` | Restore a checkpoint                            |
| `drop` | Delete a checkpoint                             |
| `run`  | Run `ps`, `cmd`, or `native` in the guest       |
| `put`  | Transfer a file from host to guest              |
| `get`  | Transfer a file from guest to host              |

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`.