# Hyper-V Permissions Explained

Quick guide to understanding Hyper-V permissions and why they don't matter for MCP usage.

---

## Current Status

**Your account:** 270015376
**Hyper-V Administrators group:** Empty (you're not a member)
**Result:** Cannot use PowerShell Hyper-V cmdlets

---

## What This Affects

### ✓ Still Works (No Admin Needed)

| Feature | How to Use | Notes |
|---------|-----------|-------|
| VM MCP Server | SSH to VM | Uses network, not Hyper-V API |
| Start/Stop VMs | Hyper-V Manager GUI | Right-click VM |
| View VM status | Hyper-V Manager GUI | Shows all VMs |
| Create snapshots | Hyper-V Manager GUI | Right-click VM -> Checkpoint |
| Restore snapshots | Hyper-V Manager GUI | Right-click snapshot -> Apply |
| Connect to VM | Hyper-V Manager GUI | Double-click VM |
| VM settings | Hyper-V Manager GUI | Right-click VM -> Settings |

**Bottom line:** Everything you need works via GUI or SSH.

### ✗ Doesn't Work (Need Group Membership)

| Feature | Why It Fails | Workaround |
|---------|-------------|-----------|
| `Get-VM` cmdlet | No Hyper-V perms | Use Hyper-V Manager GUI |
| `Checkpoint-VM` cmdlet | No Hyper-V perms | Right-click VM -> Checkpoint |
| `Restore-VMSnapshot` cmdlet | No Hyper-V perms | Right-click snapshot -> Apply |
| Scripted snapshot automation | No cmdlet access | Manual via GUI |
| Test script Hyper-V checks | No cmdlet access | Warnings are harmless |

**Bottom line:** Only PowerShell automation is blocked.

---

## Why VM MCP Works Without Admin

**VM MCP uses SSH, not Hyper-V API:**

```
Traditional approach (needs Hyper-V perms):
  Claude -> PowerShell -> Hyper-V API -> VM

VM MCP approach (no perms needed):
  Claude -> ssh-mcp -> Network -> SSH Server on VM -> Commands
```

**Key difference:** VM MCP treats the VM like any remote Windows machine. It doesn't care about Hyper-V at all.

---

## Test Results Explained

When you run `test-mcp-servers.ps1`:

```
[6/7] Checking Hyper-V VMs...
  INFO: Cannot use PowerShell Hyper-V cmdlets
  NOTE: VM MCP works via SSH - no admin needed for that!
  
[7/7] Checking VM snapshots...
  INFO: Cannot use PowerShell snapshot cmdlets
  TIP: Use Hyper-V Manager GUI to create/restore snapshots
```

**These are informational, not errors.** The test script is just explaining what you can't do via PowerShell.

---

## Getting Admin/Group Access

### Option 1: Request Group Membership (Recommended)

Ask your IT admin to add you to "Hyper-V Administrators" group:

```powershell
# Admin runs:
Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "270015376"
```

**Benefits:**
- Can use PowerShell cmdlets
- Can script VM operations
- Test script shows all green

**Drawbacks:**
- Need to request from IT
- May have approval process

### Option 2: Keep As-Is (Works Fine)

Use Hyper-V Manager GUI instead of PowerShell.

**Benefits:**
- No need to request access
- GUI is often easier than cmdlets
- VM MCP works perfectly

**Drawbacks:**
- Can't script snapshot management
- Test script shows warnings

---

## GUI Equivalents

All PowerShell operations have GUI equivalents:

### Create Snapshot
**PowerShell:**
```powershell
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"
```

**GUI:**
1. Open Hyper-V Manager
2. Right-click VM
3. Select "Checkpoint"
4. Enter name "Clean-Install"
5. Click OK

### Restore Snapshot
**PowerShell:**
```powershell
Restore-VMSnapshot -Name "Clean-Install" -VMName "ShopDB-Test-VM" -Confirm:$false
```

**GUI:**
1. Open Hyper-V Manager
2. Select VM in left pane
3. In "Checkpoints" pane (bottom), right-click "Clean-Install"
4. Select "Apply"
5. Choose "Apply" or "Apply and Create Checkpoint"

### List Snapshots
**PowerShell:**
```powershell
Get-VMSnapshot -VMName "ShopDB-Test-VM"
```

**GUI:**
1. Open Hyper-V Manager
2. Select VM
3. View "Checkpoints" pane at bottom
4. See all snapshots in tree view

### Check VM Status
**PowerShell:**
```powershell
Get-VM | Select-Object Name, State, Uptime
```

**GUI:**
1. Open Hyper-V Manager
2. View all VMs in center pane
3. See Name, State, CPU Usage, etc.

---

## Documentation Updates

The following docs have been updated to clarify admin requirements:

- `test-mcp-servers.ps1` - Shows INFO instead of WARN for Hyper-V perms
- `STATUS.md` - Explains impact (none for MCP)
- `HYPER-V-PERMISSIONS.md` - This guide

**VM-SNAPSHOT-GUIDE.md** still shows PowerShell commands, but mentions GUI alternatives.

---

## When Would You Need Admin?

**You'd only need Hyper-V admin for:**

1. **Automated snapshot scripts** - Create/restore snapshots from command line
2. **VM creation** - Creating new VMs via PowerShell
3. **Advanced scripting** - Batch operations on multiple VMs
4. **CI/CD integration** - Automated testing workflows that manage VMs

**For daily development:** GUI + VM MCP is perfectly fine.

---

## Claude Code Integration

**With VM MCP, Claude can:**
```
✓ Execute commands on VM
✓ Copy files to/from VM
✓ Read logs from VM
✓ Check service status
✓ Install/configure software
✓ Test agent deployment
✓ All via SSH - no Hyper-V perms needed!
```

**Claude cannot (without Hyper-V perms):**
```
✗ Create snapshots via PowerShell
✗ Restore snapshots via script
✗ Query VM state via Get-VM

But you can do these manually in GUI!
```

---

## Summary

**Current situation:**
- You're not in "Hyper-V Administrators" group
- VM MCP works perfectly via SSH
- Use Hyper-V Manager GUI for snapshot management
- Test script shows warnings but everything is functional

**Recommendation:**
Keep as-is unless you need automated snapshot scripting. For daily development, GUI + SSH is sufficient.

**If you want group membership:**
Request from IT admin to add you to "Hyper-V Administrators" local group.

---

## Quick Reference

| Task | Without Group | With Group |
|------|--------------|------------|
| VM MCP (SSH) | ✓ Works | ✓ Works |
| Start/stop VM | ✓ GUI | ✓ GUI or PowerShell |
| Create snapshot | ✓ GUI | ✓ GUI or PowerShell |
| Restore snapshot | ✓ GUI | ✓ GUI or PowerShell |
| View VM status | ✓ GUI | ✓ GUI or PowerShell |
| Script automation | ✗ Can't | ✓ Can |

**Bottom line: You can do everything, just not via PowerShell scripts.**

---

**No action required - setup is complete and functional!**