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.
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. |
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
Not on PyPI yet, so install straight from this repo with
uv (no manual venv needed):
claude mcp add --scope user lume-vnc -- uvx --from git+https://github.com/Blackphi6/lume-vnc-mcp lume-vnc-mcpOnce this is published to PyPI, the command will shorten to:
claude mcp add --scope user lume-vnc -- uvx lume-vnc-mcpIf your lume binary isn't on PATH, set LUME_BIN to its full path via
-e LUME_BIN=/path/to/lume on the claude mcp add command (or the
equivalent env entry in your MCP client's config).
Once registered, ask your agent things like:
"Take a screenshot of the my-vm VM"
"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.
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.
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.
MIT
指定した lume VM の画面上の座標をクリックする。button: 1=左, 2=中, 3=右。
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | ||
| y | Yes | ||
| button | No | ||
| vm_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only discloses the button mapping and that the target is the VM's screen. It does not say whether the click is relative to the screen or the window, whether it requires the VM to be focused or running, or what side effects a right/middle click may have.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, with the action front-loaded before the button enumeration. Nothing is wasted, though the extreme brevity contributes to the semantic gaps noted elsewhere.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists so return values need not be described, but for a 4-parameter GUI automation action with zero annotations, the description omits prerequisites, coordinate frame, and focus behavior — the essentials an agent needs before invoking it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, yet it only explains 'button' (1=left, 2=middle, 3=right). The meaning and units of x/y (screen vs window coordinates, pixels) and the expected vm_name format are left entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (click) and resource (a coordinate on the specified lume VM's screen), which is enough to tell it apart from type_text, key_press and screenshot by name alone. It stops short of explicitly naming how it relates to those siblings, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to prefer this over key_press or type_text, no prerequisites such as the VM needing to be running or the window needing focus, and no note on when a coordinate click is the wrong approach. The agent must infer all usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
指定した lume VM にキー(組み合わせ)を送信する。例: 'ctrl-c', 'super-shift-g', 'Return'。
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | ||
| vm_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the core effect (keystrokes are sent to the named VM) and gives key-combination syntax, but omits whether the VM must be running/focused, what happens on an invalid key, and any permission or timing requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action and immediately followed by concrete syntax examples. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter input tool with an output schema covering return values, the description is minimally adequate. However, with no annotations and zero parameter description coverage, it should say more about prerequisite VM state and parameter expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The examples add useful syntax for the 'key' parameter, but 'vm_name' is only indirectly implied by 'specified lume VM' and no format or constraints are given for either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('send key combinations to the specified lume VM'), which is clear enough to distinguish it from siblings like click and type_text. It does not explicitly name those siblings, but the action is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The examples ('ctrl-c', 'Return') imply when this tool is appropriate versus typing text, but the description never states preconditions, exclusions, or alternatives. Usage is inferable but not guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
指定した lume VM の現在の画面をスクリーンショットとして取得する。
| Name | Required | Description | Default |
|---|---|---|---|
| vm_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden. It conveys that the capture reflects the current screen state, but says nothing about what is returned (inline image vs. file path), behavior on a non-running or nonexistent VM, or whether the operation has any side effects. For a tool that produces an artifact, the return form is a notable omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-formed sentence with the resource and scope front-loaded and no filler. It is efficient, though the brevity comes at the cost of the missing behavioral detail captured under other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description should explain at minimum what the agent receives back (image content, path, URL) and any prerequisites such as the VM being active. Neither is covered, leaving an agent unable to predict the result of calling it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the single parameter vm_name is undocumented in the schema. The description only says the VM is 'specified', adding no detail on expected identifier format, naming conventions, or whether the VM must be running. It does not compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: capture the current screen of the specified lume VM as a screenshot. This is clearly distinguishable from the sibling input tools (click, type_text, key_press), which the description implicitly separates itself from by describing observation rather than interaction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool: no mention of checking VM state before/after actions, no timing or frequency constraints, and no exclusions. The intended usage is only weakly inferable from the 'current screen' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
指定した lume VM に文字列をキー入力としてタイプする。
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| vm_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden, yet it discloses nothing beyond the basic action: no mention of whether a trailing newline/enter is sent, how fast text is sent, what happens if the VM is stopped or unfocused, or whether characters outside the keyboard layout are dropped. For an input-injection tool this is a substantial gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with the action front-loaded and no filler. Its brevity is appropriate in form, though the small amount of text is also the source of the definition's gaps.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, but with zero annotation coverage and 0% schema description coverage the description should say more about focus/running-state requirements and typing semantics (newline handling, special characters) than it does.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the fields carry only titles, so the description must compensate. It does minimally: 'text' is clarified as the string typed as key input, and 'vm_name' as the lume VM targeted, which is slightly more than the bare property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('type') and resource ('string as keyboard input') and names the target ('specified lume VM'), which separates it from click, key_press and screenshot by the nature of the operation. It does not, however, explicitly contrast itself with the closest sibling key_press.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this over key_press (single key) or click, and no stated prerequisites such as the VM being running or the target window having focus. The agent must infer the selection rule from the verb alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0clickkey_pressscreenshottype_textScored 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.
The cloud Mac alone, with Xcode, for AI agents: run commands, build and test, use the screen.
Cloud desktops for AI agents: create a Linux computer, see its screen, click, type and run tasks.
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
