@sitharaj88/winctl

WinCtl

Full Windows desktop access for Claude and other MCP clients
See the screen, read and drive real application UIs, manage windows and processes, work with files, and run shell commands — all behind a tiered permission model with audit logging.

Why this connector

Most desktop automation servers hand the model a screenshot and a click(x, y) tool, which breaks the moment a window moves. This one is built around the things that actually make Windows automation reliable:

• UI Automation first. uia_snapshot reads an application's accessibility tree, so Claude can act on "the Save button" rather than on coordinates that go stale. uia_invoke and uia_set_value drive controls directly.
• Correct coordinates, always. The process declares per-monitor DPI awareness before touching any UI API, and reports the DWM frame bounds rather than the raw window rect (which includes an invisible ~7px resize border). Without this, every coordinate on a scaled display is silently wrong — on a 200% display, GetWindowRect reports 1351px where the true edge is 2641px.
• Input that actually arrives. Synthetic typing is paced, because batching Unicode key events makes applications drop and repeat characters. Text over 200 characters is pasted via the clipboard instead, and your clipboard is restored afterwards.
• Handles that cannot betray you. Window ids are opaque and fingerprinted; Windows recycles window handles, and a stale one silently retargeting to a different app is exactly how automation closes the wrong window.
• Honest failures. window_focus verifies the foreground actually changed and says so when Windows refuses. Errors explain what to do next rather than surfacing an HRESULT.

Requirements

• Windows 10 (1809+) or Windows 11
• Node.js 20 or newer
• No compiler or build tools — every native dependency ships prebuilt binaries

Install

Claude Desktop (recommended)

Download winctl.mcpb from the latest release and double-click it. Claude Desktop installs it and exposes the permission profile, allowed folders and confirmation settings in its UI.

Claude Code

Install globally first, then register the command:

npm install -g @sitharaj88/winctl
claude mcp add winctl -- winctl

Add --scope user to the second command to make it available in every project rather than just the current one.

Don't use npx -y @sitharaj88/winctl here. It works, but WinCtl depends on prebuilt native binaries (sharp, koffi), and npx re-resolves them on every launch — around 18 seconds versus 3 for a global install. MCP clients give up long before that and report Connection closed.

Any MCP client (manual)

{
  "mcpServers": {
    "winctl": {
      "command": "winctl",
      "env": {
        "WINCTL_PROFILE": "standard"
      }
    }
  }
}

If winctl isn't on your PATH, point at the entry point directly — on Windows a global npm install lands in %APPDATA%\npm\node_modules:

{
  "mcpServers": {
    "winctl": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@sitharaj88\\winctl\\dist\\index.js"]
    }
  }
}

Claude Desktop's config lives at %APPDATA%\Claude\claude_desktop_config.json.

Permission tiers

Every tool belongs to exactly one tier. Tools in a disabled tier are never registered, so the model cannot see them, attempt them, or spend context reading their descriptions.

Tier	What it allows
observe	Screenshots, window/monitor enumeration, UI trees, system and process info, file reads
interact	Mouse and keyboard input, UI Automation invokes, window focus/move/close, clipboard writes
filesystem	Creating, modifying, moving and deleting files
manage	Starting and terminating processes, controlling services
shell	Arbitrary PowerShell and cmd execution

Profiles bundle these:

Profile	Tiers
readonly	observe
standard (default)	observe, interact, filesystem
full	all five

# Pick a profile
WINCTL_PROFILE=readonly

# …or choose tiers explicitly
WINCTL_TIERS=observe,interact

Configuration

Variable	Default	Purpose
WINCTL_PROFILE	standard	readonly, standard or full
WINCTL_TIERS	—	Explicit tier list, overrides the profile
WINCTL_ALLOWED_PATHS	—	Semicolon-separated folders file tools may touch
WINCTL_DENIED_PATHS	—	Extra folders to refuse
WINCTL_CONFIRM_DESTRUCTIVE	true	Ask before destructive actions
WINCTL_AUDIT_LOG	%LOCALAPPDATA%\winctl\audit.jsonl	Audit log path
WINCTL_AUDIT_DISABLED	false	Turn auditing off
WINCTL_MAX_IMAGE_WIDTH	1600	Screenshot downscale width
WINCTL_COMMAND_TIMEOUT_MS	60000	Shell/PowerShell time limit

An unrecognised profile name fails closed to readonly with a warning on stderr, rather than guessing what you meant and possibly granting write access.

Tools

Screen (5)

Tool	Tier	Description
screen_list_monitors	observe	Displays with position, resolution and DPI scale
screen_capture	observe	Screenshot a monitor or the whole virtual desktop
screen_capture_region	observe	Screenshot a rectangular region
screen_capture_window	observe	Screenshot one window, even if overlapped
screen_list_capturable_windows	observe	Windows available for individual capture

Windows (7)

Tool	Tier	Description
window_list	observe	Visible top-level windows with stable ids and bounds
window_get_active	observe	The window with keyboard focus
window_get_desktop_info	observe	Virtual desktop bounds and cursor position
window_focus	interact	Raise and focus a window, with verification
window_set_state	interact	Minimize, maximize, restore, hide, show
window_move	interact	Move and resize (un-maximizes first)
window_close	interact	Ask a window to close

Input (7)

Tool	Tier	Description
input_move_mouse	interact	Move the cursor
input_click	interact	Click, right-click or double-click
input_drag	interact	Drag between two points, interpolated
input_scroll	interact	Scroll vertically or horizontally
input_type	interact	Type Unicode text, or paste when long
input_press_keys	interact	Chords such as ctrl+shift+escape
input_key_hold	interact	Hold or release a key

UI Automation (4)

Tool	Tier	Description
uia_snapshot	observe	Read an application's accessibility tree
uia_find	observe	Find controls by name, id or type
uia_invoke	interact	Click, toggle, expand, select or focus a control
uia_set_value	interact	Set an editable control's text directly

System & processes (8)

Tool	Tier	Description
system_info	observe	OS, CPU, memory, disks, network, battery, GPU
system_list_services	observe	Services with state and startup type
system_list_installed_apps	observe	Installed applications
system_notify	interact	Windows toast notification
system_control_service	manage	Start, stop or restart a service
process_list	observe	Processes with CPU and memory usage
process_start	manage	Launch an application or open a document
process_kill	manage	Terminate a process

Files, clipboard & shell (9)

Tool	Tier	Description
file_known_folders	observe	Standard Windows paths and current access limits
file_list	observe	Directory listing with sizes and timestamps
file_read	observe	Read text or base64 content
file_search	observe	Find files by name pattern and content
file_write	filesystem	Write, append or create
file_manage	filesystem	Copy, move, delete, mkdir
clipboard_read	observe	Read clipboard text
clipboard_write	interact	Set clipboard text
shell_run	shell	Run a PowerShell or cmd command

40 tools total. Every one carries title, readOnlyHint and destructiveHint annotations.

Example

"Open Notepad, write my meeting notes into it and save to Documents."

Claude will typically:

• process_start → launch Notepad
• window_list → find the window and its owning process id
• window_focus → make sure keystrokes land there
• input_type → paste the notes via the clipboard
• input_press_keys ctrl+s, then uia_set_value on the filename field
• screen_capture_window → confirm the result visually

Safety

• Tier gating is the primary boundary — disabled tools are never exposed.
• Path containment resolves symlinks before checking, so a link inside an allowed folder cannot reach a denied one. System32, WinSxS, Boot and the Startup folder are refused in every profile, including full.
• Confirmation via MCP elicitation before destructive actions.
• Audit log of every call in JSONL, with sensitive-looking arguments redacted. See PRIVACY.md.
• Modifier release on shutdown, so a crash mid-chord cannot leave Ctrl latched down.
• Refuses to terminate its own process or pids 0–4.

Screenshots capture whatever is on screen and send it to your AI provider. Read PRIVACY.md before enabling screen capture on a machine that handles confidential material.

Elevation

Windows blocks a normal-privilege process from automating, capturing or sending input to windows owned by elevated processes (UIPI). To drive an administrator application, run the connector elevated — otherwise those calls fail with a clear explanation rather than silently doing nothing.

Privacy Policy

WinCtl runs entirely on your machine. It has no backend, no telemetry and no analytics, and it makes no network calls of its own. The author receives nothing about you or your computer.

• What it accesses: screen contents, window and application state, system and process information, files within the folders you permit, and the clipboard — each only when a tool is called. It generates synthetic input but never records your real keyboard or mouse activity.
• Where data goes: to the AI client you connect it to, and nowhere else. Anything a tool returns becomes part of that conversation and is therefore subject to that client's privacy policy. A screenshot sends whatever is on screen to your AI provider — consider that before enabling screen capture on a machine handling confidential material.
• What is stored: only a local audit log at %LOCALAPPDATA%\winctl\audit.jsonl — one line per tool call, with sensitive-looking arguments redacted. It is never uploaded. Disable it with WINCTL_AUDIT_DISABLED=1, or delete the file at any time.
• Retention and sharing: nothing is retained off-machine and nothing is shared with third parties.
• Contact: Sitharaj Seenivasan — [e-mail]

Full policy: PRIVACY.md

Development

git clone https://github.com/sitharaj88/winctl
cd winctl
npm install
npm run build

npm run smoke                 # self-test against the live desktop
node scripts/smoke.mjs --full # full MCP protocol suite, including UI Automation
npm run inspect               # MCP Inspector UI

scripts/verify-interactive.mjs drives Notepad end-to-end — it launches the app, types, verifies the text through UI Automation and cleans up. It uses the real mouse and keyboard, so don't run it while you're using the machine.

Architecture

src/
  index.ts              stdio entry point (DPI awareness runs first)
  http.ts               streamable HTTP entry point, loopback-only by default
  config.ts             profiles, tiers, limits
  security/             tier definitions, path containment, audit log, errors
  native/
    ffi.ts              koffi bindings to user32/kernel32/dwmapi
    dpi.ts              per-monitor DPI awareness
    handles.ts          opaque, fingerprinted window ids
    windows.ts          enumeration, focus, move, state
    input.ts            SendInput mouse and keyboard
    screen.ts           capture and token-aware encoding
    powershell.ts       per-call PowerShell execution
    uia.ts              UI Automation bridge
  server/
    registry.ts         tier gate + confirmation + audit in one place
    createServer.ts     assembles tools, resources and prompts
  tools/                the 40 tool definitions

Two implementation notes worth knowing if you extend this:

• PowerShell runs one process per call. A long-lived host sounds better, but -Command - buffers all of stdin until the stream closes rather than executing statement by statement, so it never returns a result. Per-call processes also mean a hung script can't wedge later calls. Commands are passed as -EncodedCommand (base64 UTF-16LE), which removes shell quoting as a source of injection bugs.
• The INPUT struct size is asserted at startup. A layout mismatch wouldn't throw — it would send mouse events to garbage coordinates.

Publishing

npm run build && npm publish --access public   # npm
npx @anthropic-ai/mcpb pack                    # build the .mcpb bundle
mcp-publisher login github && mcp-publisher publish   # MCP registry

For the Claude Connectors Directory, submit desktop extensions via the extension form.

Author

Sitharaj Seenivasan

• Website — sitharaj.in
• GitHub — @sitharaj88
• LinkedIn — in/sitharaj08
• Email — [e-mail]

Issues and feature requests are welcome at github.com/sitharaj88/winctl/issues.

Licence

MIT © Sitharaj Seenivasan