MCP Server

Lume supports the Model Context Protocol (MCP), allowing AI agents like Claude Desktop and Claude Cowork to manage VMs directly through native tool integration.

┌─────────────────────────────────────────────────────────────────┐
│                      Your Mac (Host)                            │
│                                                                 │
│  ┌──────────────────┐           ┌───────────────────────────┐  │
│  │ Claude Desktop   │◄── MCP ──►│ Lume MCP Server           │  │
│  │ or Claude Cowork │  (stdio)  │ (lume serve --mcp)        │  │
│  └──────────────────┘           └─────────────┬─────────────┘  │
│                                               │                 │
│                                               │ VM Control      │
│                                               ▼                 │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │                   macOS VM Sandbox                          ││
│  │  Claude can: create, list, run, stop, clone, delete, exec   ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

Quick setup

1. Configure Claude Desktop

Run this command to automatically configure Claude Desktop:

mkdir -p ~/Library/Application\ Support/Claude && cat > ~/Library/Application\ Support/Claude/claude_desktop_config.json << EOF
{
  "mcpServers": {
    "lume": {
      "command": "$(which lume)",
      "args": ["serve", "--mcp"]
    }
  }
}
EOF

Or manually edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lume": {
      "command": "/Users/yourname/.local/bin/lume",
      "args": ["serve", "--mcp"]
    }
  }
}

If editing manually, replace /Users/yourname/.local/bin/lume with the actual path to your lume binary. You can find it by running which lume in your terminal.

2. Restart Claude Desktop

Claude will now have access to Lume's VM management tools.

3. Try it out

Ask Claude:

"List my VMs"
"Start the sandbox VM"
"Run ls -la in the sandbox VM"
"Stop the sandbox VM"

Available tools

Tool	Description
`lume_create_vm`	Create a new macOS VM (async, returns immediately)
`lume_list_vms`	List all VMs with status, IP addresses, and resource allocation
`lume_get_vm`	Get detailed VM info (IP, VNC URL, SSH availability)
`lume_run_vm`	Start a VM with optional shared directory
`lume_stop_vm`	Stop a running VM gracefully
`lume_clone_vm`	Clone a VM (useful for golden images)
`lume_delete_vm`	Delete a VM and its files
`lume_exec`	Execute commands inside a VM via SSH

Resources

The MCP server provides documentation resources that AI agents can read:

Resource	Description
`lume://usage-guide`	Comprehensive guide with workflows, best practices, and status reference
`lume://credentials`	Default SSH credentials for VMs created with unattended setup

Prompts

Pre-defined workflow prompts guide AI agents through common tasks:

Prompt	Description
`create-sandbox`	Create a new macOS VM with unattended setup
`run-in-sandbox`	Execute a command in an existing VM
`reset-sandbox`	Reset a sandbox by cloning from a golden image

The lume_create_vm tool creates new macOS VMs asynchronously. Since VM creation takes 15-30 minutes (downloading IPSW, installing macOS, optional unattended setup), the tool returns immediately while provisioning continues in the background.

Parameters

Parameter	Required	Default	Description
`name`	Yes	-	Name for the new VM
`ipsw`	No	`latest`	IPSW path or "latest" to download
`unattended`	No	-	Preset name (e.g., "tahoe", "sequoia") for automatic setup
`cpu`	No	4	Number of CPU cores
`memory`	No	`8GB`	Memory size (e.g., "8GB", "16GB")
`disk_size`	No	`64GB`	Disk size (e.g., "64GB", "128GB")
`storage`	No	-	Storage location name or path

Provisioning status

During creation, VMs show a provisioning status with the current operation:

NAME      STATUS                           IP
sandbox   provisioning (ipsw_install)      -
dev-vm    running                          192.168.64.3
test      stopped                          -

The operation progresses through:

ipsw_install — Downloading and installing macOS
unattended_setup — Running Setup Assistant automation (if unattended specified)

Poll lume_list_vms or lume_get_vm to monitor progress. Once complete, status changes to stopped.

Example

You: Create a new sandbox VM with unattended setup

Claude: I'll create a new macOS VM with automatic configuration.

[Calls lume_create_vm with name="sandbox", unattended="tahoe"]

VM 'sandbox' creation started. Status: provisioning.
I'll monitor the progress...

[Calls lume_list_vms periodically]
Status: provisioning (ipsw_install)...
Status: provisioning (unattended_setup)...
Status: stopped

The sandbox VM is ready! Would you like me to start it?

Command execution

The lume_exec tool runs commands inside VMs via SSH. It requires:

SSH enabled in the VM (automatic with --unattended tahoe)
sshpass installed on your host for password-based auth

# Install sshpass
brew install hudochenkov/sshpass/sshpass

For VMs created with --unattended tahoe:

Username: lume
Password: lume

Example workflow

Here's what an AI agent interaction looks like:

You: Create a sandbox VM and run my tests

Claude: I'll set up a sandbox and run your tests.

[Calls lume_list_vms to check existing VMs]

No sandbox VM exists. I'll create one with unattended setup.

[Calls lume_create_vm with name="sandbox", unattended="tahoe"]

VM creation started. This will take 15-30 minutes.
I'll monitor the progress and let you know when it's ready.

[Polls lume_list_vms until status changes from "provisioning" to "stopped"]

The sandbox is ready! Now starting it with your project directory shared.

[Calls lume_run_vm with name="sandbox", shared_dir="~/project"]
[Calls lume_get_vm to get IP address]
[Calls lume_exec with command="cd /Volumes/My\ Shared\ Files && npm test"]

Tests completed! Here are the results:
✓ 42 tests passed
✗ 2 tests failed
...

MCP vs HTTP API

Feature	MCP Server	HTTP Server
Command	`lume serve --mcp`	`lume serve`
Transport	stdio (spawned by client)	HTTP (port 7777)
Use case	AI agent integration	Scripts, CI/CD, SDKs
Lifecycle	On-demand, client-managed	Background daemon

Use MCP for AI agent integration. Use HTTP for programmatic access from scripts and applications.

Testing with MCP Inspector

Debug your MCP setup with the official inspector:

npx @modelcontextprotocol/inspector lume serve --mcp

This opens a web UI where you can:

See all available tools
Test tool calls interactively
Inspect request/response payloads

Troubleshooting

Claude doesn't see Lume tools

Check the config file path is correct
Verify lume is accessible (try running lume --version)
Restart Claude Desktop completely (quit and reopen)

lume_exec fails with "sshpass not found"

Install sshpass:

brew install hudochenkov/sshpass/sshpass

lume_exec fails with "no IP address"

The VM might not be running or hasn't acquired an IP yet:

# Check VM status
lume ls

# Start the VM if needed
lume run my-vm --no-display

# Wait a few seconds for IP assignment
lume get my-vm

SSH connection refused

Ensure SSH is enabled in the VM. For existing VMs:

# Connect via VNC and enable in System Settings > Sharing > Remote Login
# Or if you can SSH with a different method:
ssh lume@<ip> "sudo launchctl load -w /System/Library/LaunchDaemons/ssh.plist"

New VMs created with --unattended tahoe have SSH enabled automatically.

Security considerations

The MCP server gives AI agents direct control over your VMs. Only use it with trusted AI applications.

The MCP server:

Runs locally (stdio transport, no network exposure)
Has full access to VM lifecycle operations
Can execute commands inside VMs with SSH access

Consider:

Using dedicated sandbox VMs for AI agent tasks
Cloning VMs before letting agents modify them
Reviewing agent actions in Claude's interface

Claude Cowork Sandbox — MCP-based sandbox workflow
Claude Code Sandbox — SSH-based sandbox setup
HTTP Server — REST API for scripts and CI/CD
Unattended Setup — Automated VM configuration

Was this page helpful?