lume-vnc-mcp
This MCP server lets an AI agent see and control an already-running lume macOS VM over VNC through four raw tools.
Take PNG screenshots of the VM’s current screen.
Click at screen coordinates with left, middle, or right mouse buttons.
Type text into the VM one key event per character.
Send individual keys or key combinations such as
ctrl-c,super-shift-g, orReturn.
It does not manage VM lifecycle; it only interacts with a VM that is already running.
Lets an agent see and control the screen of a running macOS virtual machine over VNC, exposing screenshot, click, type_text, and key_press primitives so it can drive real app UIs inside the isolated VM.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lume-vnc-mcp take a screenshot of the my-vm VM"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
lume-vnc-mcp
A tiny MCP server that lets an AI agent (Claude Code, Claude Desktop, or any other MCP client) see and control the screen of a lume macOS virtual machine over VNC — without ever touching your real desktop.
This is useful when you want an agent to click through a real app's UI (for a demo, a test, or a screen recording) in a disposable, isolated environment instead of your actual machine.
It exposes exactly 4 tools, nothing more:
Tool | What it does |
| Returns a PNG screenshot of the VM's current screen |
| Moves the mouse and clicks at |
| Types a string, one key event per character |
| Sends a key or key combo, e.g. |
Prerequisites
macOS on Apple Silicon
lume installed and a VM created and running (
lume create,lume run) — this server does not manage VM lifecycle, it only talks to a VM that is already running. For that, pair it with lume's own built-in MCP server (lume serve --mcp), which handles create/start/stop.
Related MCP server: VNC MCP Server
Install
This is a plain MCP server over stdio — nothing in it is Claude-specific. It works with any MCP-compatible client: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, VS Code (with an MCP-capable extension), and so on.
Not on PyPI yet, so install straight from this repo with
uv (no manual venv needed). Once published
to PyPI, drop --from git+https://github.com/Blackphi6/lume-vnc-mcp and
just use uvx lume-vnc-mcp.
Claude Code
claude mcp add --scope user lume-vnc -- uvx --from git+https://github.com/Blackphi6/lume-vnc-mcp lume-vnc-mcpAny other MCP client (Claude Desktop, Cursor, Windsurf, Cline, Continue, ...)
Add this to that client's MCP config file (for Claude Desktop,
claude_desktop_config.json; for Cursor, .cursor/mcp.json; etc. — see your
client's own docs for the exact file and location):
{
"mcpServers": {
"lume-vnc": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Blackphi6/lume-vnc-mcp",
"lume-vnc-mcp"
]
}
}
}If your lume binary isn't on PATH, set LUME_BIN to its full path: add
-e LUME_BIN=/path/to/lume on the claude mcp add command, or an "env": {"LUME_BIN": "/path/to/lume"} entry next to "command" in the JSON above.
Usage
Once registered, ask your agent things like:
"Take a screenshot of the
my-vmVM""Click the button at 500, 300 in
my-vm""Type 'hello world' into
my-vm"
Pair it with lume's own MCP mode (lume serve --mcp, see
trycua/cua) so the same agent can also
create, start and stop the VM itself.
Why not just use the full cua agent stack?
trycua/cua also ships cua-mcp-server,
which is a higher-level tool: you hand it a natural-language task and it
runs its own internal agent loop (with its own, separately billed, model
API key) to complete it autonomously.
lume-vnc-mcp is the opposite: it exposes only the raw primitives
(screenshot / click / type / key) and lets your existing agent — the one
you're already talking to — drive the VM directly, call by call, with no
extra model, no extra API key, and no extra cost.
Security note
These tools give an agent full mouse/keyboard control of whatever is running inside the target VM. Only point this at a VM you trust the agent to operate, and never at a VM that has your real accounts or private data signed in — the whole point is that it's disposable.
License
MIT
Available Tools
4 toolsclickC
指定した lume VM の画面上の座標をクリックする。button: 1=左, 2=中, 3=右。
Inputs: x (required), y (required), vm_name (required), button. Returns: result
key_pressB
指定した lume VM にキー(組み合わせ)を送信する。例: 'ctrl-c', 'super-shift-g', 'Return'。
Inputs: key (required), vm_name (required). Returns: result
screenshotC
指定した lume VM の現在の画面をスクリーンショットとして取得する。
Inputs: vm_name (required).
type_textC
指定した lume VM に文字列をキー入力としてタイプする。
Inputs: text (required), vm_name (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a clearly distinct VNC action: clicking, typing text, pressing keys, and taking a screenshot. There is little overlap, so an agent can select the correct tool unambiguously.
All names are lowercase snake_case and action-oriented, but the patterns vary: click is a bare verb, type_text is verb_noun, key_press is noun_verb, and screenshot is a noun. This is mostly consistent and readable, with minor deviations.
Four tools is a tight, well-scoped set for basic VNC interaction, with each tool earning its place. It avoids bloat while covering the core input/output primitives.
The set covers clicking, typing, key combinations, and screenshots, but omits common VNC operations such as mouse move, drag, scroll, and double-click. These gaps will force workarounds or cause failures in many GUI automation workflows.
Maintenance
Related MCP Connectors
Real desktops for AI agents, on machines you choose: screenshot, type, click, hire more agents.
Let your AI agent control real iPhones: screenshots, tap, swipe, type and open apps.
The cloud Mac alone, with Xcode, for AI agents: run commands, build and test, use the screen.
A cloud Linux desktop for your AI: browse, click, type, read the screen and run commands.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI to remotely control macOS systems via VNC with full desktop capabilities including screenshots, mouse control, keyboard input, and application management. Includes a web-based chat interface for natural language control.810MIT
- AlicenseBqualityDmaintenanceEmpowers AI agents to see, reason, and control computers via VNC, providing advanced vision features like OCR and image search, human-like input control, and optional SSH remote command execution.211MIT
- AlicenseAqualityDmaintenanceEnables AI agents to control macOS desktop apps via screenshots, mouse clicks, keyboard input, accessibility queries, and AppleScript.118 npmMIT
- AlicenseAqualityDmaintenanceEnables AI agents to remotely control computers via VNC, including mouse movement, clicking, keyboard input, text entry, and screen capture across Windows, Linux, and macOS systems.6307 npmMIT