lowlevel-computer-use-mcp
This server provides comprehensive low-level desktop automation via an MCP interface, giving unsandboxed control over mouse, keyboard, windows, processes, screen capture, and more — across Windows and Linux.
Mouse & Keyboard Control
Move, click (single/double/right/middle), drag, and scroll the mouse
Click background/unfocused windows via Win32 messages
Type text into focused or background windows; press hotkey combinations (e.g.
Ctrl+C,Alt+Tab)
Screen Capture & Recording
Screenshot full screen, specific monitor, region, or individual window (even hidden/minimized)
Crop saved images to a sub-region
Record screen activity to MP4 files (start/stop/status)
Window Management
List, move, resize, focus, minimize, maximize, restore, show, hide, and close windows
Enumerate child controls (class, text, rect, handle)
Set control text via
WM_SETTEXTwithout focusing; send keys to background windows
Process Management
List running processes (PID, name, memory, CPU) and kill by PID or name
Shell & Admin Commands
Run arbitrary shell commands with stdout/stderr/exit code capture
Run commands as Administrator (UAC elevation); check server elevation status
Headless / Off-Screen GUI (Windows)
Create off-screen Win32 desktops, launch GUI apps invisibly, list/screenshot their windows
Temporarily show the headless desktop for human interaction (e.g. login), then hide it
AutoHotkey Integration
Check AHK availability, run inline AHK scripts, use
ControlSend/ControlClickfor reliable background input
Linux / X11 Support
Check X11 tool availability (xdotool, wmctrl, Xvfb)
Create and manage Xvfb virtual displays; launch, automate, and screenshot headless GUI apps
Ephemeral WSL (Windows)
Provision throwaway WSL distros (Alpine or cloned), run commands inside them, then destroy them
Auto-Start & Boot Persistence
Install/uninstall a logon scheduled task for automatic server startup; check task status
General
Get screen resolution and current cursor position
CLI fallback: run any tool directly from the command line without an MCP connection
All tools return consistent
{"ok": true, ...}or{"ok": false, "error": "..."}JSON responses
Allows running AutoHotkey scripts and using ControlSend/ControlClick for reliable background window input.
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 take a screenshot of my main monitor"
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
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: device-controller-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
🚀 Silent auto-start —
pythonw.exestarts the local HTTP server with no terminal window; elevation is opt-in🟢 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 — a no-MCP command-line fallback that runs any tool directly from CLI args, for when MCP connections keep failing
⚠️ 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 older 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 |
| 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, and registers the
server with both Claude Code and Codex automatically on launch.
Clone the repo:
git clone https://github.com/codingmachineedge/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 so they spawn the server.
Manual install
Install dependencies and start the stdio server:
uv run lowlevel-computer-use-mcpOr with pip — install in editable mode:
pip install -e .Then run it:
lowlevel-computer-use-mcpRemote 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 --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.
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 same local cheap-tool API and starts 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.
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": "uv",
"args": ["run", "--directory", "C:\\path\\to\\lowlevel-computer-use-mcp", "lowlevel-computer-use-mcp"]
}
}
}Codex (OpenAI Codex CLI)
Add this block to ~/.codex/config.toml:
[mcp_servers.lowlevel-computer-use]
command = "uv"
args = ["run", "--directory", "C:\\path\\to\\lowlevel-computer-use-mcp", "lowlevel-computer-use-mcp"]
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 (no-MCP fallback)
If MCP connections keep failing, you don't need MCP at all. The Cheap Version is a command-line fallback that runs the exact same tool functions in-process and prints the JSON result — no client, transport, or server connection involved.
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 --adminCheck elevation:
is_admin {}Console-free startup
Install the default per-user Startup launcher. It uses wscript.exe plus
pythonw.exe, opens no terminal window, binds HTTP only to localhost, and needs no
UAC prompt:
uv run lowlevel-computer-use-mcp install-startupAn elevated Scheduled Task is an explicit opt-in and may show UAC during setup:
uv run lowlevel-computer-use-mcp install-startup --admin-taskUse a custom port:
uv run lowlevel-computer-use-mcp install-startup --port 9000Check the task status:
uv run lowlevel-computer-use-mcp startup-statusRemove it:
uv run lowlevel-computer-use-mcp uninstall-startupOnce the boot service runs in HTTP mode, point a client at it as a remote MCP server:
claude mcp add --transport http lowlevel-computer-use-boot http://127.0.0.1:8765/mcpThe startup process owns no top-level window. 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
Available Tools
57 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
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 57 tools
Several tools occupy nearly identical roles: create_headless_desktop and create_headless_desktops differ mainly by count, run_command and run_command_as_admin overlap heavily, and type_text/win_send_keys/win_set_control_text/ahk_control_send all deliver text or keys with subtle targeting differences. An agent would frequently need to read descriptions very carefully to avoid misselection.
The set is predominantly snake_case verb_noun (list_windows, move_window, kill_process), and subsystem prefixes like wsl_, win_, and ahk_ give a predictable rhythm. Minor deviations such as window_action, recording_status, and create_headless_desktops are still readable and do not seriously break the pattern.
57 tools far exceeds the well-scoped 3–15 range and crosses the 50+ extreme threshold. Even for a broad computer-use server, this is too many tools to navigate coherently, and several clusters could be consolidated without losing capability.
The domain is covered deeply: lifecycle support exists for windows, processes, headless desktops, virtual displays, WSL distros, recording, and admin tasks. Minor gaps remain (no clipboard, no general file listing, no dedicated Linux window listing), but run_command provides an escape hatch and there are no severe dead ends.
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA standalone MCP server for Windows desktop control, enabling screenshots, mouse and keyboard input, app launch, window/display management, and clipboard access via natural language.3MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that lets Claude Desktop and Claude Code control your PC — take screenshots, click, type, manage windows, and more.MIT
- AlicenseNot gradedqualityBmaintenanceAn MCP server that lets Claude operate your real computer by moving the actual mouse, clicking, typing, and reading the actual screen, working with your own logged-in sessions in any application.83 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceA framework-agnostic computer-use MCP server that exposes core desktop operations (screen capture, mouse, keyboard, and file access) as standard MCP tools, enabling any MCP-compatible agent to drive a computer.MIT