a03fd3de4f
- Replace all unicode (emojis, checkmarks, arrows, em-dashes) with ASCII in .claude/ docs - Comment out OperatingSystemsList route in core.js - breaks lean builds without computers plugin - Comment out Operating Systems tab in ModelCatalogHub - TODO: Plugins should dynamically register their settings routes Fixes #2 CI check failures on wj branch Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
250 lines
6.2 KiB
Markdown
250 lines
6.2 KiB
Markdown
# 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
|
|
|
|
### [X] 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:**
|
|
```
|
|
[X] Execute commands on VM
|
|
[X] Copy files to/from VM
|
|
[X] Read logs from VM
|
|
[X] Check service status
|
|
[X] Install/configure software
|
|
[X] Test agent deployment
|
|
[X] 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) | [X] Works | [X] Works |
|
|
| Start/stop VM | [X] GUI | [X] GUI or PowerShell |
|
|
| Create snapshot | [X] GUI | [X] GUI or PowerShell |
|
|
| Restore snapshot | [X] GUI | [X] GUI or PowerShell |
|
|
| View VM status | [X] GUI | [X] GUI or PowerShell |
|
|
| Script automation | [ ] Can't | [X] Can |
|
|
|
|
**Bottom line: You can do everything, just not via PowerShell scripts.**
|
|
|
|
---
|
|
|
|
**No action required - setup is complete and functional!**
|