lowlevel-computer-use-mcp
This MCP server enables background GUI automation and system control on Windows and Linux, with isolated headless desktops as the main feature.
Create and manage off-screen Windows desktops or Linux Xvfb displays for real GUI apps.
Launch GUI apps headlessly; list, capture, and automate their windows without disturbing the visible desktop.
Temporarily show a headless desktop for human login with a non-dismissible banner and emergency exit.
Control mouse: move, click (including background window targeting), drag, scroll, get cursor position.
Control keyboard: type text, press hotkeys, send keys to background windows, set control text.
Capture screenshots of monitors, regions, windows, or virtual displays; crop images; record screen to mp4.
Manage windows: list, move, resize, focus, minimize, maximize, restore, close, show/hide.
Manage processes: list and kill by PID or name.
Run shell commands and capture output; run elevated commands with UAC/admin rights.
Transfer files to/from the controlled computer via base64 upload/download.
Use AutoHotkey for reliable background input and scripting.
Use Linux X11 automation tools and Xvfb virtual displays.
Provision ephemeral WSL distros on Windows, run commands, and destroy them.
Install/uninstall boot startup tasks and check admin/startup/recording/status endpoints.
Multi-agent support: create multiple named headless desktops namespaced by project/agent.
Focus-safe: background actions avoid focus stealing; foreground actions require explicit confirmation.
Allows running AutoHotkey scripts, with ControlSend and ControlClick for reliable background window input automation.
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., "@lowlevel-computer-use-mcp Run notepad on a headless desktop and take a screenshot"
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.
lowlevel-computer-use-mcp
Exact hidden-desktop resize adds explicit desktop/identity/geometry binding. Source controls do not establish runtime acceptance.
Real GUI apps. Zero desktop clutter. Give an MCP agent a desktop of its own.
Explore the project site · Jump to quick start
The headline feature is headless desktop automation: run full native GUI applications on an invisible Windows desktop or Linux Xvfb display, then let an agent capture, click, and type without stealing focus or disturbing the desktop you are using.
create isolated desktop → launch real GUI app → automate off-screen → capture & verifyWhen a login or other human-only step is unavoidable, the agent can temporarily reveal that desktop. A non-dismissible top banner tells the user exactly what to do, and an EMERGENCY EXIT button immediately returns to the normal desktop.
Why headless-with-GUI?
🫥 Invisible by default — apps retain a real GUI while staying off your visible desktop
🎯 No focus stealing — background mouse, keyboard, and control targeting keep your workflow uninterrupted
📸 Still observable — capture individual windows even while they are occluded, unfocused, or off-screen
🧑💻 Safe human handoff — reveal the desktop only when needed, with persistent instructions and emergency return
🪟 Native on Windows — isolated Win32 desktops via
CreateDesktopandSwitchDesktop🐧 Native on Linux — virtual GUI displays backed by Xvfb
Related MCP server: desktop-touch-mcp
Everything else agents need
This low-level computer-use MCP server works with Codex, Claude Code, Claude Desktop, and other MCP clients. Headless desktops are the centerpiece; the same server also exposes the primitives needed to automate and verify them end to end:
🫥 Headless GUI — run real GUI apps on an off-screen desktop; show them only when a human login is needed
🎯 Background / unfocused targeting — drive a specific window via Win32 messages without focusing it
🧩 Multi-agent desktops — create and list independent named desktops in one request; namespace them by project and agent
🧑🤝🧑 Subagent lanes — persist project/agent namespaces so later agents can pick up the same quiet room
🚫 Quiet process policy — Windows child processes use hidden startup information and CREATE_NO_WINDOW; headless launches never create a terminal or switch the user's input desktop
📸 Screenshots — all monitors, one monitor, a region, or one window via PrintWindow
🖱️ Mouse — move, click, double/right/middle click, drag, scroll, cursor position
⌨️ Keyboard — type text, press hotkey combinations (Ctrl+C, Alt+Tab, …)
🖥️ Shell commands — run arbitrary system commands and capture output
🪟 Windows — list, move, resize, focus, minimize, maximize, restore, close, show/hide
⚙️ Processes — list running processes; kill by PID or name
✂️ Cropping — crop any saved image to a sub-region
🎥 Screen recording — record a monitor or region to mp4 in the background
🛡️ Run-as-admin — per-command UAC elevation or whole-server elevation
🚀 Quiet client registration —
pythonw.exekeeps the compatibility MCP stdio entry out of the user's desktop; no HTTP logon service is installed🟢 AutoHotkey add-in — run AHK scripts;
ControlSend/ControlClickfor rock-solid background input🐧 Cross-platform — the same tools work natively on Linux (X11 via xdotool/wmctrl), with Xvfb virtual displays for headless-with-GUI
🌀 Ephemeral WSL — on a Windows host, spin up a throwaway Linux distro on demand, run commands, tear it down
🧩 GUI installer — one window that installs everything automatically
💸 Cheap Version — the primary local command-line route that runs any registered tool directly from CLI args, without MCP or a listening server
🧱 Native Windows resilience — an in-process C++ desktop bridge owns hidden-desktop handles, while a console-free C++ stdio supervisor restarts an unexpectedly terminated MCP child with bounded backoff
⚠️ This server performs real, unsandboxed actions on the host machine — clicking, typing, killing processes and running shell/elevated commands with your user's privileges. Only register it in environments where that is acceptable.
This public repository carries a sanitized mirror of the shared agent instructions. The canonical instructions remain the source of truth.
Apply safety, accessibility, language, Material 3, appearance, search, tabs, export, notification, and version-history rules to every app and Pages surface, including nested dialogs and documentation.
Use headless computer-use first; keep child processes console-free and never steal focus. Use visible handoff only when required, with an emergency exit.
Keep secrets out of chat, source, arguments, URLs, logs, screenshots, and history. Use a temporary secure intake for sensitive values.
Use
gitandghfor repository work. Preserve unrelated changes, commit and push intended work to the default branch, prove the pushed SHA, and never force-push or delete unmerged work.Keep README, feature articles, roadmap, handoff, wiki, Pages, API docs, changelog, screenshots, issue evidence, and releases truthful and current.
Ship English, playful Hong Kong Cantonese, and bilingual modes with two persisted funny-level controls; humour changes voice, never facts.
Provide a bounded local regex builder beside every search, complete tabs and bulk actions, accessible Material 3 appearance editing, command palette, export, local append-only revisions, and restore-as-new-revision behavior.
Test before publishing one unique real release per push/dispatch, verify hosted checks and live endpoints, and use only verified local/catalog assets.
Electron manual client
The Electron client is the local GUI for the same MCP surface. It creates
project/agent headless rooms, hosts the trusted-LAN API, saves named computer
connections for later agents, runs any tool by name, keeps local history, and
provides persisted language, funny-level, tab, appearance, notification, and
changelog controls. The GitHub Pages site
remains the primary explanatory guide; the detailed feature articles live in
docs/features.
Run the manual client from electron/ with npm install followed by npm start.
Its startup path repairs the Electron runtime when the package is present but
its binary cache is missing. Quick launch has an inline application browser;
the Tool runner has file and folder browsers that write safe JSON path values.
The Tab manager supports named groups, persistent collapse state, searchable
context menus, and reviewable bulk close by visible tab text with optional regex.
The Memory page saves settings, connections, subagent lanes, and tab layout as
named local checkpoints; restores create new Git-backed revisions in app data.
The Tool runner also sends and receives bounded files through the selected local
or saved LAN computer, using a user-controlled native Save dialog for receives.
The Settings appearance editor also supports per-target typography, spacing,
translated colors, built-in presets, and saved user presets with reset and
export/import.
Each build also carries a factual public dim-sum code name and catalog-photo link
in the Manual and Changelog surfaces; the photo is referenced, never copied.
The Windows release target is Squirrel.Windows and the local packaging command
is npm run package.
Real Electron screenshots
These captures come from the Electron renderer's offscreen capture mode, so no terminal or visible desktop window was opened while they were produced.









Tools
Tool | Description |
| Primary screen resolution |
| Current mouse position |
| Smoothly move cursor to |
| Smoothly move then click; |
| Press-drag-release between two points |
| Scroll the wheel up/down |
| Type text; |
| Press a key / hotkey combo, e.g. |
| Run a shell command, capture output/exit code |
| List top-level windows (title, handle, geometry, state) |
| Info about the focused window |
| Move / resize a window |
| focus / minimize / maximize / restore / close |
| Bring a window forward (e.g. for login), then hide it again |
| Enumerate a window's child controls (class, text, rect, handle) |
| Set a control's text via WM_SETTEXT (reliable background text) |
| Post key presses to a window without focusing it |
| List processes; kill by PID or name |
| Monitor/region/single-window (PrintWindow) capture to PNG |
| Crop an existing image to a box |
| mp4 recording |
| Create an off-screen desktop |
| Report whether the C++ desktop bridge is active and the exact Python fallback reason |
| Create multiple independent desktops with explicit names or a generated project/agent prefix |
| List desktops owned by this server process and their window counts |
| Launch a GUI app onto it |
| List windows on the off-screen desktop |
| Temporarily make it interactive (login), then hide |
| Release the off-screen desktop handle |
| Whether AutoHotkey is installed |
| Run an inline AutoHotkey script |
| AHK ControlSend to a background window/control |
| Whether the server is running elevated |
| Run a shell command elevated (UAC prompt) |
| Boot auto-start |
| Linux: X11 automation tooling availability |
| Linux: start an Xvfb headless display |
| Linux: launch a GUI app on the Xvfb display |
| Linux: windows on the Xvfb display |
| Linux: capture the whole Xvfb display |
| Linux: stop the Xvfb display |
| WSL availability + installed distros |
| Provision a throwaway WSL distro (Alpine by default) |
| Run a command inside a WSL distro |
| Manage throwaway distros |
Every tool returns a JSON string {"ok": true, ...} on success or
{"ok": false, "error": "..."} on failure.
Quick start (GUI installer — fully automatic)
The easiest path. It installs uv if missing, runs uv sync, registers a quiet
stdio compatibility server with the supported clients, and removes the retired
HTTP/logon registration so local tool calls use the Cheap Version.
Clone the repo:
git clone https://github.com/Ding-Ding-Projects/lowlevel-computer-use-mcp.gitEnter it:
cd lowlevel-computer-use-mcpSync once, then launch the GUI-subsystem installer directly. This avoids creating a terminal window for the installer itself:
uv sync
.\.venv\Scripts\lowlevel-computer-use-mcp-installer.exeThen restart Claude Code / Codex / OpenCode so they reload the quiet compatibility registration. The installer does not create a persistent HTTP server or a Windows logon launcher.
Manual install
The normal local route is the Cheap Version; it starts no MCP transport and no HTTP listener:
uv run lowlevel-computer-use-cheap --listFor a client that still needs MCP stdio, install dependencies and start the compatibility server:
uv run lowlevel-computer-use-mcpOr with pip — install in editable mode:
pip install -e .Then run it:
lowlevel-computer-use-mcpOptional legacy Remote LAN API
The server already exposes MCP over Streamable HTTP. On the computer being controlled, bind it to the LAN interface:
uv run lowlevel-computer-use-mcp --http --legacy-http --host 0.0.0.0 --port 8765Agents on the trusted LAN connect to http://<computer-ip>:8765/mcp; health
checks use http://<computer-ip>:8765/health. This mode intentionally has no
API key because it is designed for a trusted home/LAN network. Anyone who can
reach the port can control the computer with the server's user privileges, so
use Windows Firewall or a private VLAN and never forward port 8765 to the
public internet.
This compatibility transport is never enabled by the installer, GUI, or Windows
logon startup. The Electron client can save a named connection and route manual tool calls to
POST http://<computer-ip>:8765/api/execute with a JSON body such as:
{"tool":"list_headless_desktops","arguments":{}}The Electron manual client uses the Cheap Version for local tool calls and starts compatibility child processes with hidden Windows startup flags, so dependency installation and manual tool calls do not open terminal windows.
Captures (screenshots, recordings) are written to
~/lowlevel-computer-use-captures by default. Override with the
LOWLEVEL_CU_CAPTURE_DIR environment variable.
Registering with clients
Replace the path below with wherever you cloned this repo. These entries are the quiet compatibility MCP stdio path; use the Cheap Version directly for ordinary local tool calls.
Claude Code
Register at user scope (one line):
claude mcp add lowlevel-computer-use --scope user -- "C:\path\to\lowlevel-computer-use-mcp\.venv\Scripts\pythonw.exe" -m lowlevel_computer_use_mcp.serverOr add this to ~/.claude.json under mcpServers:
{
"mcpServers": {
"lowlevel-computer-use": {
"command": "C:\\path\\to\\lowlevel-computer-use-mcp\\.venv\\Scripts\\pythonw.exe",
"args": ["-m", "lowlevel_computer_use_mcp.server"]
}
}
}Codex (OpenAI Codex CLI)
Add this block to ~/.codex/config.toml:
[mcp_servers.lowlevel-computer-use]
command = "C:\\path\\to\\lowlevel-computer-use-mcp\\.venv\\Scripts\\pythonw.exe"
args = ["-m", "lowlevel_computer_use_mcp.server"]
startup_timeout_sec = 60YOLO mode (auto-approve, no permission prompts)
The GUI installer enables this by default. To do it manually for Claude Code, add a
wildcard allow rule for this server's tools to ~/.claude/settings.json:
{ "permissions": { "allow": ["mcp__lowlevel-computer-use__*"] } }For Codex, set the global approval policy in ~/.codex/config.toml:
approval_policy = "never"⚠️ YOLO means every tool runs without asking — including destructive ones (
kill_process,run_command,run_command_as_admin,wsl_destroy). Only enable it if you trust the agents driving this server.
Cheap Version (primary local route)
The Cheap Version is the primary local route. It runs the exact same registered tool functions in-process and prints the JSON result — no client, transport, HTTP listener, or persistent server connection involved. MCP stdio and the HTTP API remain compatibility paths for clients that explicitly require them.
List every available tool:
uv run lowlevel-computer-use-cheap --listTake a screenshot:
uv run lowlevel-computer-use-cheap screenshot --monitor 1Double-click at a point:
uv run lowlevel-computer-use-cheap mouse_click --x 960 --y 540 --clicks 2Press a hotkey (values are parsed as JSON, so lists work):
uv run lowlevel-computer-use-cheap press_keys --keys '["ctrl","s"]'Run a shell command:
uv run lowlevel-computer-use-cheap run_command --command "ipconfig /all"Pass a whole argument object as JSON:
uv run lowlevel-computer-use-cheap screenshot --json '{"window_title":"Notepad"}'The same thing is also available as a subcommand of the main entry point:
uv run lowlevel-computer-use-mcp cheap get_screen_sizeEvery parameter from the Tool Reference is accepted as --<param> <value>
(or via --json). Output is the identical {"ok": true, ...} JSON the MCP tools return.
Agent skill — every feature documented
A companion skill (skills/lowlevel-computer-use/) teaches agents the entire
toolset: a top-level SKILL.md plus reference/TOOLS.md (exhaustive per-tool
parameters), reference/WORKFLOWS.md (end-to-end recipes) and
reference/PLATFORMS.md (Windows/Linux specifics & gotchas). Install it for Claude
Code by copying it into your skills directory:
cp -r skills/lowlevel-computer-use ~/.claude/skills/The MCP server also ships condensed instructions inline, so any MCP client gets a full feature overview on connect.
Background / unfocused window targeting
Headless execution is the default operating model. mouse_click, type_text and
screenshot accept hwnd or window_title. When
set, input is delivered to that exact window via Win32 messages without focusing
or foregrounding it, and screenshot uses PrintWindow so the window is captured
even if it's behind others, minimized, or on an off-screen desktop.
Typical flow:
Find the window:
list_windows { "title_filter": "Notepad" }Find the control to target:
list_child_windows { "window_title": "Notepad" }Set its text in the background (most reliable for edit controls):
win_set_control_text { "hwnd": 23924320, "text": "typed without focus" }Or click it in the background (x/y are client coords of the window):
mouse_click { "window_title": "Notepad", "x": 200, "y": 120 }See the result without bringing it forward:
screenshot { "window_title": "Notepad" }Caveat: message-based input is ignored by some apps (raw input / DirectInput / physical-key-state checks). Try AutoHotkey
ahk_control_send; do not silently fall back to foreground input while the user is active.
Foreground mouse, typing, hotkeys, window activation, and interactive desktop
switches are focus-protected. They return focus_protected: true unless the call
includes confirm_focus_disruption: true after the user explicitly requests a
visible handoff.
Headless-but-with-GUI mode
Run a real GUI app on an off-screen Win32 desktop so it never touches your visible desktop, then automate and screenshot it via the background tools.
Create the off-screen desktop:
create_headless_desktop { "name": "work" }Launch an app onto it:
launch_on_headless_desktop { "name": "work", "command": "notepad.exe" }List its windows (to get handles):
list_headless_windows { "name": "work" }Each returned window includes its handle, process_id, thread_id, dpi,
title, class, width, and height. Identity and DPI are sampled inside the
desktop enumeration callback; an unavailable value is reported as 0 without
omitting the window.
Capture a window on it (works even though it's off-screen):
screenshot { "hwnd": 2495156 }Showing it for an interactive login, then hiding again
Some steps (sign-in) need a human. Temporarily switch the live screen to the off-screen desktop:
show_headless_desktop {
"name": "work",
"instruction": "Sign in to the app, then tell the agent you are done.",
"confirm_focus_disruption": true
}The interactive desktop has a topmost banner that cannot be closed. It displays the instruction and includes an EMERGENCY EXIT button that immediately returns the user to the normal desktop. After the user finishes, switch back normally:
hide_headless_desktop { "name": "work" }For an ordinary hidden window on the normal desktop, use show_window /
hide_window instead:
show_window { "window_title": "My App", "confirm_focus_disruption": true }hide_window { "window_title": "My App" }AutoHotkey add-in
Optional but powerful. AHK's ControlSend/ControlClick drive background windows
very reliably, and run_ahk is a full scripting escape hatch.
Install AutoHotkey (one line):
winget install -e --id AutoHotkey.AutoHotkeyCheck the server can find it:
ahk_status {}Send text to a background window by HWND:
ahk_control_send { "text": "hello", "window": "ahk_id 0x1A2B3C" }Run an arbitrary AHK script (must call ExitApp):
run_ahk { "code": "ControlSendText \"hi\", , \"ahk_exe notepad.exe\"\nExitApp" }Point the server at a specific AHK exe by setting LOWLEVEL_CU_AHK to its path.
Macros — save repeated sequences as Skills
When you run a multi-step UI sequence the user is likely to repeat, don't leave
it as ad-hoc tool calls — capture it as a reusable macro Skill. The server tells
agents to do this automatically; see
macros/MACRO_SKILL_TEMPLATE.md for the template
and rules (resolve handles at run time, prefer background tools, parameterize the
variable parts, verify with a screenshot).
Linux (native X11)
The mouse, keyboard, screenshot, process, recording, window management and
background/unfocused targeting tools all work natively on Linux. Window control,
background input and per-window capture use X11 CLI tools; on Linux hwnd is an X11
window id.
Install the X11 helpers (Debian/Ubuntu):
sudo apt install xdotool wmctrl x11-utils imagemagick xvfbCheck what the server can see:
linux_status {}Background-type into a window without focusing it (X11):
type_text { "window_title": "Editor", "text": "typed in the background" }Caveat: X11 background typing uses
XSendEvent; most apps accept it, but a few (notablyxtermwith its defaultallowSendEvents: false) ignore synthetic events. For those, use Xvfb or report the limitation; do not steal the user's focus.
Headless-with-GUI on Linux (Xvfb)
Start a virtual display:
create_virtual_display { "display": 99, "width": 1280, "height": 800 }Launch a GUI app onto it:
launch_on_virtual_display { "display": 99, "command": "xterm -e bash" }List its windows:
list_virtual_display_windows { "display": 99 }Drive a window on that display (note the display field routes input there):
type_text { "hwnd": 2097164, "display": 99, "text": "hello from headless" }Capture the whole virtual display:
screenshot_virtual_display { "display": 99 }Stop it when done:
stop_virtual_display { "display": 99 }Ephemeral WSL (Linux on a Windows host)
On Windows, spin up a throwaway Linux distro on demand to run Linux software, then tear it down. By default a tiny Alpine minirootfs is downloaded and imported in seconds — your existing distros are untouched.
Check WSL is available:
wsl_status {}Provision a throwaway distro (downloads latest Alpine minirootfs):
wsl_create_temp {}Run a command in it (use the name returned above):
wsl_run { "distro": "llcu-tmp-1782754365-53b8", "command": "apk add --no-cache curl && curl --version" }Tear it down (irreversible — deletes the distro):
wsl_destroy { "name": "llcu-tmp-1782754365-53b8" }You can also clone an existing distro instead of downloading:
wsl_create_temp { "clone_from": "Ubuntu-24.04" }Run-as-admin mode
Per-command elevation — call run_command_as_admin (UAC prompt unless already
elevated):
run_command_as_admin { "command": "net session" }Or run the whole server elevated (intended for HTTP mode):
uv run lowlevel-computer-use-mcp --http --legacy-http --adminCheck elevation:
is_admin {}Console-free startup and legacy retirement
The old persistent HTTP/logon launcher is retired. The GUI installer removes its registration and the legacy HTTP entries from Claude, Codex, and OpenCode. To repeat that cleanup manually, run:
uv run lowlevel-computer-use-mcp retire-legacy-startupinstall-startup now refuses by default, so an accidental invocation cannot
bring the old HTTP window back. It accepts --legacy-http only as an explicit
compatibility escape hatch for an existing client that cannot yet migrate:
uv run lowlevel-computer-use-mcp install-startup --legacy-http --port 8765Do not use that compatibility option for normal local calls. Use the Cheap
Version instead. The quiet MCP stdio client registration uses pythonw.exe, and
the packaged Electron app starts its local helper with hidden Windows startup
flags; neither path installs a new logon HTTP service.
To inspect or remove any old registration:
uv run lowlevel-computer-use-mcp startup-status
uv run lowlevel-computer-use-mcp uninstall-startupNo new top-level console window is created by the Cheap Version or quiet stdio
registration. Tool-spawned Windows child processes also use CREATE_NO_WINDOW
plus SW_HIDE. See
runtime safety.
Local regex builder
The bundled Python re builder supports guided literals, character classes,
anchors, groups, alternation and quantifiers, plus raw patterns, flags, sample
text, syntax feedback, captures, copy/export, and plain-text search mode. It
evaluates in a console-free subprocess with strict size, time, and match limits.
uv run lowlevel-computer-use-regex-builder --start --literal "ID:" --char-class "0-9" --quantifier "+" --end --sample "ID:42"uv run lowlevel-computer-use-regex-builder --pattern "^(?P<word>\\w+)$" --flags m --sample "HongKong`nToronto"Language settings (en, yue, bilingual) and independent English/Cantonese
funny levels (1..5) persist only when explicitly changed. Patterns and samples
are never persisted or transmitted. See regex builder documentation.
Requirements
Python 3.10+
uv (recommended; the GUI installer can bootstrap it)
Windows: mouse/keyboard via
pyautogui; windows viapygetwindow; background input + capture + headless desktop viactypes/Win32 (winio.py); screenshots viamss; recording viaimageio+ bundled ffmpeg. Optional: AutoHotkey, WSL.Linux: mouse/keyboard via
pyautogui(X11); window mgmt, background input and per-window capture viaxdotool/wmctrl/x11-utils/ImageMagick (linuxio.py); headless-with-GUI viaXvfb; screenshots/recording viamss. Install the X11 helpers with your package manager (see the Linux section). X11 (or XWayland) session.
Safety notes
run_command,run_command_as_admin,kill_process,run_ahkandwindow_action(close)are marked destructive.pyautogui's fail-safe is disabled so automation isn't interrupted by the cursor reaching a screen corner; be deliberate with coordinates.The server has no authentication of its own — it trusts the MCP client that spawns it.
License
MIT
Reproducible Windows package producers
Run build.bat for the isolated locked Python wheel and build-installer.bat for the existing manual-client Squirrel.Windows installer. Both bootstrap their required tools without modifying another environment. Packaging is unsigned and may trigger unknown-publisher or SmartScreen warnings. See producer details and verification limits.
If a running server is using .venv, preserve that server and run build.bat /s -EnvironmentPath .bootstrap/build-venv to build in a separate environment. The selected environment supplies both dependency synchronization and bytecode validation; the wheel output stays in dist/. The default remains .venv. Do not replace an environment while a server is using it.
Current bounded recovery evidence
Source 1fe2a321c22114dd921be9f27b51c0e97b4ace36 passed exact build.bat /s
and build-installer.bat /s, with 122 unchanged tracked inputs per producer.
Independent byte audit covered 18,728 unique paths with zero differences. The
Squirrel full package passed all 89 entries and RELEASES hash/size verification;
setup and project executables are unsigned. A source-bound native hidden resize
also reached renderer 800x600 at physical client 1200x900 and DPI144/DPR1.5.
See the verification summary and
current handoff for prior failures, exact hashes and limits.
Installation/update lifecycle, optional generated catalog packaging, packaged
runtime, fresh-machine bootstrap and actual release/publication remain unverified.
Background navigation keys preserve enhanced-key identity. See behavior and verification.
Available Tools
59 toolsahk_control_sendA
Send text or keystrokes to a background window/control via AutoHotkey ControlSend.
Works without focusing the window and is often more reliable than raw WM_CHAR for complex apps. Target a HWND with 'ahk_id '.
Args: params (AhkControlSendInput): text, window/control targets, as_keys, timeout.
Returns: str: JSON with the AHK run result.
Inputs: params (required). Returns: result
ahk_statusARead-onlyIdempotent
Report whether AutoHotkey is installed and where.
Returns: str: JSON {"ok": true, "installed": bool, "path": "...", "version": "v2", ...}.
Inputs: no named parameters. Returns: result
close_headless_desktopADestructiveIdempotent
Release this server's handle to an off-screen desktop.
The desktop is fully freed by Windows once no process is still running on it, so close any apps you launched there first.
Args: params (HeadlessDesktopInput): desktop name.
Returns: str: JSON {"ok": true, "name": "...", "closed": bool}.
Inputs: params (required). Returns: result
create_headless_desktopAIdempotent
Create an off-screen Win32 desktop for running GUI apps invisibly.
Apps launched on this desktop have a real GUI (so they run and can be automated and captured via PrintWindow) but never appear on the visible desktop. This is the 'headless but with GUI' mode.
Args: params (HeadlessDesktopInput): desktop name.
Returns: str: JSON {"ok": true, "name": "...", "handle": N, "full": "WinSta0\..."}.
Inputs: params (required). Returns: result
create_headless_desktopsAIdempotent
Create several independent off-screen desktops in one request.
Use a project/agent-specific prefix or explicit names when several
agents share a Windows session. Existing names are reopened safely.
Inputs: params (required). Returns: result
create_virtual_displayAIdempotent
Start an Xvfb virtual display — the Linux 'headless but with GUI' mode.
GUI apps launched on it run with a real X server but no physical screen, so they can be automated (xdotool) and screenshotted (mss) without occupying the visible desktop. The Linux counterpart of the Windows headless desktop.
Args: params (CreateVirtualDisplayInput): display number, width, height, depth.
Returns: str: JSON {"ok": true, "display": ":99", "size": "1280x800x24", "pid": N}.
Inputs: params (required). Returns: result
crop_imageAIdempotent
Crop an existing image file to a rectangular sub-region.
Args: params (CropInput): source path, crop box (left/top/width/height), output path.
Returns: str: JSON {"ok": true, "path": "...", "width": W, "height": H}.
Inputs: params (required). Returns: result
download_fileARead-onlyIdempotent
Read a file from the controlled computer as base64, up to 50 MiB.
Inputs: params (required). Returns: result
get_active_windowARead-onlyIdempotent
Return information about the currently focused (active) window.
Returns: str: JSON with the active window's title, handle, position and size, or {"ok": true, "window": null} if none is active.
Inputs: no named parameters. Returns: result
get_cursor_positionARead-onlyIdempotent
Return the current mouse cursor position in screen pixels.
Returns: str: JSON like {"ok": true, "x": 100, "y": 200}.
Inputs: no named parameters. Returns: result
get_screen_sizeARead-onlyIdempotent
Return the primary screen resolution in pixels.
Returns: str: JSON like {"ok": true, "width": 1920, "height": 1080}.
Inputs: no named parameters. Returns: result
hide_headless_desktopA
Switch the live screen back to the normal desktop after show_headless_desktop.
Args: params (HeadlessDesktopInput): the off-screen desktop name (for symmetry).
Returns: str: JSON {"ok": true, "restored": true}.
Inputs: params (required). Returns: result
hide_windowAIdempotent
Hide a window again after it was shown (e.g. once login is complete).
Args: params (HideWindowInput): the window by hwnd or title, and a minimize flag.
Returns: str: JSON {"ok": true, "hwnd": N, "visible": false}.
Inputs: params (required). Returns: result
install_startupADestructiveIdempotent
Install a scheduled task so this server starts automatically at user logon.
By default the task runs without elevation and launches the server in HTTP mode through pythonw.exe, so logon produces no terminal or focus change.
Args: params (InstallStartupInput): run_as_admin, http, host and port options.
Returns: str: JSON {"ok": bool, "output": "...", "task_name": "...", "run_as_admin": bool}.
Inputs: params (required). Returns: result
is_adminARead-onlyIdempotent
Report whether this server process is running elevated (as Administrator).
Returns: str: JSON {"ok": true, "is_admin": bool, "platform": "Windows"}.
Inputs: no named parameters. Returns: result
kill_processADestructive
Kill a process by PID, or all processes matching an exact name.
Provide either pid (preferred) or name. force=true kills hard; otherwise
a graceful terminate is requested first. This is destructive and may cause the
target application to lose unsaved data.
Args: params (KillProcessInput): pid or name, and force flag.
Returns: str: JSON {"ok": true, "killed": [{pid, name}], "count": N}, or an error.
Inputs: params (required). Returns: result
launch_on_headless_desktopADestructive
Launch a GUI application on an off-screen desktop (creates it if needed).
The process runs with a full GUI on the hidden desktop. Use list_headless_windows to find its windows, then drive them with background input and capture them with screenshot(hwnd=...). The visible desktop is never touched.
Args: params (LaunchHeadlessInput): desktop name and command line.
Returns: str: JSON {"ok": true, "desktop": "...", "pid": N, "command": "..."}.
Inputs: params (required). Returns: result
launch_on_virtual_displayADestructive
Launch a GUI app on an Xvfb virtual display (creates it if needed).
Args: params (LaunchVirtualInput): display number and command line.
Returns: str: JSON {"ok": true, "display": ":99", "pid": N, "command": "..."}.
Inputs: params (required). Returns: result
linux_statusARead-onlyIdempotent
Report Linux X11 automation tooling availability (xdotool, wmctrl, Xvfb, …).
Returns: str: JSON {"ok": true, "display": ":0", "session_type": "x11", "xdotool": bool, ...}.
Inputs: no named parameters. Returns: result
list_child_windowsARead-onlyIdempotent
Enumerate the child controls of a window (class, text, client rect, handle).
Useful for finding the exact control handle to target with background input - e.g. the 'Edit' control inside Notepad - and its position for background clicks.
Args: params (WinTargetInput): the parent window by hwnd or title.
Returns: str: JSON {"ok": true, "parent_hwnd": N, "count": N, "children": [ {handle, class, text, left, top, width, height, visible}, ...]}. Coordinates are relative to the parent window's top-left.
Inputs: params (required). Returns: result
list_headless_desktopsARead-onlyIdempotent
List all headless desktops owned by this server process.
Inputs: no named parameters. Returns: result
list_headless_windowsARead-onlyIdempotent
List the top-level windows living on an off-screen desktop.
Args: params (HeadlessDesktopInput): desktop name.
Returns: str: JSON {"ok": true, "name": "...", "count": N, "windows": [ {handle, process_id, thread_id, dpi, title, class, width, height}, ...]}.
Inputs: params (required). Returns: result
list_processesARead-onlyIdempotent
List running processes with pid, name, memory and CPU usage.
Args: params (ListProcessesInput): optional name filter, sort key and limit.
Returns: str: JSON {"ok": true, "count": N, "processes": [{pid, name, username, memory_mb, cpu_percent}, ...]}.
Inputs: params (required). Returns: result
list_virtual_display_windowsARead-onlyIdempotent
List the windows present on an Xvfb virtual display.
Args: params (VirtualDisplayInput): display number.
Returns: str: JSON {"ok": true, "count": N, "windows": [...]}.
Inputs: params (required). Returns: result
list_windowsARead-onlyIdempotent
List top-level windows with their titles, handles, positions and sizes.
Args: params (ListWindowsInput): optional title filter and empty-title toggle.
Returns: str: JSON {"ok": true, "count": N, "windows": [{title, handle, left, top, width, height, is_minimized, is_maximized, is_active}, ...]}.
Inputs: params (required). Returns: result
mouse_clickA
Click a mouse button, optionally at a specific coordinate.
Use clicks=2 for a double-click. If x/y are omitted the click happens at the current cursor position.
BACKGROUND TARGETING: set hwnd or window_title to click a specific window
WITHOUT bringing it to the foreground (Win32 PostMessage). In that mode x/y are
client coordinates of the target window and the deepest child control at that
point receives the click.
Args: params (ClickInput): position, button, click count, interval, optional target.
Returns: str: JSON describing the click that was performed.
Inputs: params (required). Returns: result
mouse_dragA
Press a mouse button at a start point and release it at an end point.
Args: params (DragInput): optional start, required end, button and duration.
Returns: str: JSON describing the drag.
Inputs: params (required). Returns: result
mouse_moveBIdempotent
Move the mouse cursor to an absolute screen coordinate.
Args: params (MoveInput): x, y target and optional animation duration.
Returns: str: JSON with the resulting cursor position.
Inputs: params (required). Returns: result
mouse_scrollB
Scroll the mouse wheel vertically.
Args: params (ScrollInput): amount (positive up / negative down) and optional position.
Returns: str: JSON confirming the scroll amount.
Inputs: params (required). Returns: result
move_windowAIdempotent
Move a window to a new top-left screen position.
Identify the window by handle (preferred, exact) or title (substring).
Args: params (MoveWindowInput): target window plus new x, y.
Returns: str: JSON with the window's updated geometry, or an error if not found.
Inputs: params (required). Returns: result
native_backend_statusARead-onlyIdempotent
Report whether the in-process C++ desktop bridge is active or why Python is the fallback.
Inputs: no named parameters. Returns: result
press_keysC
Press a keyboard combination (hotkey), e.g. Ctrl+C or Alt+Tab.
A single-element list presses one key; multiple elements are pressed together.
Args: params (HotkeyInput): list of pyautogui key names.
Returns: str: JSON confirming the keys pressed.
Inputs: params (required). Returns: result
recording_statusARead-onlyIdempotent
Report whether a screen recording is currently active.
Returns: str: JSON {"ok": true, "recording": bool, "path": str|null, "frames": N, "elapsed_seconds": S|null}.
Inputs: no named parameters. Returns: result
resize_windowAIdempotent
Resize a window to a new width and height.
Args: params (ResizeWindowInput): target window plus new width, height.
Returns: str: JSON with the window's updated geometry, or an error if not found.
Inputs: params (required). Returns: result
run_ahkADestructive
Run an inline AutoHotkey script and capture its output.
The script MUST terminate (call ExitApp, or be non-persistent) or it runs until the timeout. Emit output with FileAppend to the target "*" (stdout). AHK is ideal for reliable background input (ControlSend/ControlClick) and real hotkeys.
Args: params (RunAhkInput): script source, optional args, timeout, optional exe path.
Returns: str: JSON {"ok": bool, "returncode": int, "stdout": "...", "stderr": "...", "exe": "..."}.
Inputs: params (required). Returns: result
run_commandBDestructive
Run a system/shell command and capture its stdout, stderr and exit code.
This executes arbitrary commands on the host with the server's privileges.
Args: params (RunCommandInput): command, shell flag, cwd and timeout.
Returns: str: JSON like {"ok": true, "returncode": 0, "stdout": "...", "stderr": "...", "timed_out": false}.
Inputs: params (required). Returns: result
run_command_as_adminADestructive
Run a shell command with Administrator privileges.
If the server is not already elevated this triggers a Windows UAC prompt that the user must approve. Output is captured and returned. This runs commands with full administrative rights - use with care.
Args: params (RunAsAdminInput): the command line and a timeout.
Returns: str: JSON {"ok": bool, "returncode": int, "output": "...", "elevated_prompt": bool}.
Inputs: params (required). Returns: result
screenshotARead-only
Capture a screenshot of a monitor (or a pixel region) and save it as PNG.
BACKGROUND CAPTURE: set hwnd or window_title to capture one specific window
via Win32 PrintWindow - this works even when the window is NOT focused, is hidden
behind other windows, or runs on an off-screen/headless desktop.
Args: params (ScreenshotInput): monitor index, optional region, output path, optional window target and client_only flag.
Returns: str: JSON {"ok": true, "path": "...", "width": W, "height": H}.
Inputs: params (required). Returns: result
screenshot_virtual_displayARead-only
Capture the whole Xvfb virtual display to a PNG.
Args: params (ScreenshotVirtualInput): display number and output path.
Returns: str: JSON {"ok": true, "path": "...", "width": W, "height": H}.
Inputs: params (required). Returns: result
show_headless_desktopA
Temporarily switch the live screen to a headless desktop for human interaction.
The entire off-screen desktop (and the apps running on it) becomes interactive
and visible, so a person can complete a LOGIN or any manual step. A topmost,
non-dismissible banner explains what to do and provides an EMERGENCY EXIT button
that immediately restores the normal desktop. Call hide_headless_desktop to
switch back normally afterwards.
Args: params (ShowHeadlessDesktopInput): desktop name and banner instruction.
Returns: str: JSON {"ok": true, "name": "...", "visible": true, "safety_banner": true, "note": "..."}.
Inputs: params (required). Returns: result
show_windowAIdempotent
Make a hidden/minimized window visible and bring it to the foreground.
Useful when an automated app on the normal desktop hits a step that needs the
human - typically an interactive LOGIN. Show it, let the user sign in, then call
hide_window to tuck it away and resume background automation.
Args: params (WinTargetInput): the window by hwnd or title.
Returns: str: JSON {"ok": true, "hwnd": N, "visible": true}.
Inputs: params (required). Returns: result
start_screen_recordingA
Begin recording the screen to an mp4 file in a background thread.
Only one recording can run at a time. Call stop_screen_recording to finish
and flush the file.
Args: params (StartRecordingInput): fps, monitor, optional region and output path.
Returns: str: JSON {"ok": true, "path": "...", "fps": N, "recording": true}.
Inputs: params (required). Returns: result
startup_statusARead-onlyIdempotent
Report whether the boot-startup scheduled task is installed and its state.
Returns: str: JSON {"ok": bool, "installed": bool, "details": "...", "task_name": "..."}.
Inputs: no named parameters. Returns: result
stop_screen_recordingA
Stop the active screen recording and finalize the mp4 file.
Returns: str: JSON {"ok": true, "path": "...", "frames": N, "duration_seconds": S}.
Inputs: no named parameters. Returns: result
stop_virtual_displayADestructiveIdempotent
Stop an Xvfb virtual display and terminate the apps launched on it.
Args: params (VirtualDisplayInput): display number.
Returns: str: JSON {"ok": true, "display": ":99", "stopped": true}.
Inputs: params (required). Returns: result
type_textA
Type a string of text into the currently focused window/control.
BACKGROUND TARGETING: set hwnd or window_title to deliver the text to a
specific window WITHOUT focusing it (Win32 WM_CHAR to its focused control).
For edit controls, win_set_control_text is more reliable.
Args: params (TypeInput): the text, optional per-key interval, optional target.
Returns: str: JSON confirming how many characters were typed.
Inputs: params (required). Returns: result
uninstall_startupADestructiveIdempotent
Remove user startup without showing UAC; elevated tasks may require an elevated server.
Returns: str: JSON {"ok": bool, "output": "...", "task_name": "..."}.
Inputs: no named parameters. Returns: result
upload_fileADestructive
Write a base64 file payload to the controlled computer.
Inputs: params (required). Returns: result
window_actionADestructive
Focus, minimize, maximize, restore or close a window.
close is destructive - it sends the window a close request and the app may
prompt to save. Identify the window by handle or title.
Args: params (WindowActionInput): target window plus the action to run.
Returns: str: JSON confirming the action, or an error if the window was not found.
Inputs: params (required). Returns: result
win_send_keysA
Post key presses to a specific window WITHOUT focusing it (Win32 messages).
Args: params (WinSendKeysInput): target window plus key names.
Returns: str: JSON confirming the keys posted to the resolved control.
Inputs: params (required). Returns: result
win_set_control_textAIdempotent
Set a control's text directly via WM_SETTEXT (reliable, no focus needed).
Pass the control's hwnd (from list_child_windows) - e.g. the Edit control of
a background Notepad - to replace its text without bringing the window forward.
Args: params (WinSetTextInput): target control by hwnd (preferred) or title, plus text.
Returns: str: JSON {"ok": true, "target_hwnd": N, "text_len": N}.
Inputs: params (required). Returns: result
wsl_create_tempA
Provision a throwaway WSL distro on demand for running Linux software.
By default downloads a tiny Alpine minirootfs (a few MB) and imports it, leaving existing distros untouched. Use wsl_run to run commands in it and wsl_destroy to tear it down. Alternatively clone_from an existing distro or import base_tar.
Args: params (WslCreateInput): optional name, rootfs_url, clone_from, base_tar, timeout.
Returns: str: JSON {"ok": true, "name": "...", "install_dir": "...", "source": "alpine"}.
Inputs: params (required). Returns: result
wsl_destroyADestructiveIdempotent
Terminate and unregister a WSL distro, deleting its files (irreversible).
Args: params (WslDestroyInput): distro name and whether to delete files.
Returns: str: JSON {"ok": true, "name": "...", "destroyed": true}.
Inputs: params (required). Returns: result
wsl_destroy_all_tempADestructiveIdempotent
Tear down every throwaway distro provisioned in this session.
Returns: str: JSON {"ok": true, "destroyed": [...], "count": N}.
Inputs: no named parameters. Returns: result
wsl_list_distrosARead-onlyIdempotent
List installed WSL distros with state, version and default flag.
Returns: str: JSON {"ok": true, "count": N, "distros": [{name, state, version, default}, ...]}.
Inputs: no named parameters. Returns: result
wsl_list_tempARead-onlyIdempotent
List the throwaway distros this server session provisioned.
Returns: str: JSON {"ok": true, "count": N, "distros": [{name, install_dir, source, created_at}, ...]}.
Inputs: no named parameters. Returns: result
wsl_runADestructive
Run a shell command inside a WSL distro and capture stdout/stderr/exit code.
Args: params (WslRunInput): distro, command, optional user, cwd and timeout.
Returns: str: JSON {"ok": true, "distro": "...", "returncode": N, "stdout": "...", "stderr": "..."}.
Inputs: params (required). Returns: result
wsl_statusARead-onlyIdempotent
Report whether WSL is available on this Windows host.
Returns: str: JSON {"ok": true, "available": bool, "version": "...", ...}.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 59 tools
Many tools have clearly documented distinct purposes, but there is real overlap across families: background input can be done via type_text, win_send_keys, or ahk_control_send, and create_headless_desktop vs create_headless_desktops are easily confused, as are show_window/show_headless_desktop and the several list_*_windows variants. Descriptions help, but an agent must read carefully to pick the right one.
Nearly everything is snake_case with a predictable verb_noun pattern (list_windows, move_window, kill_process, wsl_run). Minor deviations exist: some noun-first status tools (window_action, startup_status, is_admin) and three different input-naming families (type_text vs win_send_keys vs ahk_control_send), but casing and readability stay consistent.
59 tools is heavy and well into the over-scoped range. The domain is genuinely broad (Windows GUI input, headless desktops, Linux Xvfb, WSL, recording, admin), which justifies more than average, but the count still imposes high selection costs and several tools are thin parallels of each other.
Coverage is extensive and lifecycle-aware: create/launch/list/close for headless desktops and virtual displays, create/run/list/destroy for WSL, plus full input, window, process, file, screenshot, and recording surfaces. Only minor gaps (e.g. clipboard access, richer window attribute queries) keep it from a 5.
Maintenance
Related MCP Connectors
Real desktops for AI agents, on machines you choose: screenshot, type, click, hire more agents.
Eyes and hands on real Windows PCs — observe, click, type via Glasswarp API.
Cloud desktops for AI agents: create a Linux computer, see its screen, click, type and run tasks.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI clients to automate Windows desktop applications through window manipulation, image recognition, OCR, keyboard/mouse simulation, and memory operations via the MCP protocol.MIT
- AlicenseAqualityCmaintenanceAllows AI clients to see and control Windows 10/11 desktops via MCP, with screenshots, UI Automation, Chrome CDP, keyboard/mouse, and terminal using semantic element targeting.30MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible AI platforms to see the screen and operate any desktop software through real mouse clicks, text input, key presses, and scripted scenario execution.MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to control Windows desktop applications through UI Automation and Win32, supporting window management, mouse/keyboard input, element inspection, screenshots, OCR, macro recording, and autonomous multi-app missions. It also provides an HTTP/stdio MCP interface, an operator UI, and optional telemetry and safety controls.MIT