shopdb-flask/.claude/setup/HYPER-V-SETUP.md

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:

# 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:

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:

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:

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:

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!