{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/icon-256.png\" width=\"128\" height=\"128\" alt=\"WinCtl\">\n</p>\n\n<h1 align=\"center\">WinCtl</h1>\n\n<p align=\"center\">\n  <b>Full Windows desktop access for Claude and other MCP clients</b><br>\n  See the screen, read and drive real application UIs, manage windows and\n  processes, work with files, and run shell commands — all behind a tiered\n  permission model with audit logging.\n</p>\n\n[![npm](https://img.shields.io/npm/v/@sitharaj88/winctl)](https://www.npmjs.com/package/@sitharaj88/winctl)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n\n---\n\n## Why this connector\n\nMost desktop automation servers hand the model a screenshot and a `click(x, y)`\ntool, which breaks the moment a window moves. This one is built around the\nthings that actually make Windows automation reliable:\n\n- **UI Automation first.** `uia_snapshot` reads an application's accessibility\n  tree, so Claude can act on *\"the Save button\"* rather than on coordinates that\n  go stale. `uia_invoke` and `uia_set_value` drive controls directly.\n- **Correct coordinates, always.** The process declares per-monitor DPI\n  awareness before touching any UI API, and reports the DWM frame bounds rather\n  than the raw window rect (which includes an invisible ~7px resize border).\n  Without this, every coordinate on a scaled display is silently wrong — on a\n  200% display, `GetWindowRect` reports 1351px where the true edge is 2641px.\n- **Input that actually arrives.** Synthetic typing is paced, because batching\n  Unicode key events makes applications drop and repeat characters. Text over\n  200 characters is pasted via the clipboard instead, and your clipboard is\n  restored afterwards.\n- **Handles that cannot betray you.** Window ids are opaque and fingerprinted;\n  Windows recycles window handles, and a stale one silently retargeting to a\n  different app is exactly how automation closes the wrong window.\n- **Honest failures.** `window_focus` verifies the foreground actually changed\n  and says so when Windows refuses. Errors explain what to do next rather than\n  surfacing an HRESULT.\n\n## Requirements\n\n- Windows 10 (1809+) or Windows 11\n- Node.js 20 or newer\n- No compiler or build tools — every native dependency ships prebuilt binaries\n\n## Install\n\n### Claude Desktop (recommended)\n\nDownload `winctl.mcpb` from the\n[latest release](https://github.com/sitharaj88/winctl/releases) and\ndouble-click it. Claude Desktop installs it and exposes the permission profile,\nallowed folders and confirmation settings in its UI.\n\n### Claude Code\n\nInstall globally first, then register the command:\n\n```bash\nnpm install -g @sitharaj88/winctl\nclaude mcp add winctl -- winctl\n```\n\nAdd `--scope user` to the second command to make it available in every project\nrather than just the current one.\n\n> **Don't use `npx -y @sitharaj88/winctl` here.** It works, but WinCtl depends on\n> prebuilt native binaries (sharp, koffi), and npx re-resolves them on every\n> launch — around 18 seconds versus 3 for a global install. MCP clients give up\n> long before that and report `Connection closed`.\n\n### Any MCP client (manual)\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"winctl\": {\n      \"command\": \"winctl\",\n      \"env\": {\n        \"WINCTL_PROFILE\": \"standard\"\n      }\n    }\n  }\n}\n```\n\nIf `winctl` isn't on your `PATH`, point at the entry point directly — on Windows\na global npm install lands in `%APPDATA%\\npm\\node_modules`:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"winctl\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\<you>\\\\AppData\\\\Roaming\\\\npm\\\\node_modules\\\\@sitharaj88\\\\winctl\\\\dist\\\\index.js\"]\n    }\n  }\n}\n```\n\nClaude Desktop's config lives at\n`%APPDATA%\\Claude\\claude_desktop_config.json`.\n\n## Permission tiers\n\nEvery tool belongs to exactly one tier. **Tools in a disabled tier are never\nregistered**, so the model cannot see them, attempt them, or spend context\nreading their descriptions.\n\n| Tier | What it allows |\n|---|---|\n| `observe` | Screenshots, window/monitor enumeration, UI trees, system and process info, file reads |\n| `interact` | Mouse and keyboard input, UI Automation invokes, window focus/move/close, clipboard writes |\n| `filesystem` | Creating, modifying, moving and deleting files |\n| `manage` | Starting and terminating processes, controlling services |\n| `shell` | Arbitrary PowerShell and cmd execution |\n\nProfiles bundle these:\n\n| Profile | Tiers |\n|---|---|\n| `readonly` | `observe` |\n| `standard` *(default)* | `observe`, `interact`, `filesystem` |\n| `full` | all five |\n\n```bash\n# Pick a profile\nWINCTL_PROFILE=readonly\n\n# …or choose tiers explicitly\nWINCTL_TIERS=observe,interact\n```\n\n### Configuration\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `WINCTL_PROFILE` | `standard` | `readonly`, `standard` or `full` |\n| `WINCTL_TIERS` | — | Explicit tier list, overrides the profile |\n| `WINCTL_ALLOWED_PATHS` | — | Semicolon-separated folders file tools may touch |\n| `WINCTL_DENIED_PATHS` | — | Extra folders to refuse |\n| `WINCTL_CONFIRM_DESTRUCTIVE` | `true` | Ask before destructive actions |\n| `WINCTL_AUDIT_LOG` | `%LOCALAPPDATA%\\winctl\\audit.jsonl` | Audit log path |\n| `WINCTL_AUDIT_DISABLED` | `false` | Turn auditing off |\n| `WINCTL_MAX_IMAGE_WIDTH` | `1600` | Screenshot downscale width |\n| `WINCTL_COMMAND_TIMEOUT_MS` | `60000` | Shell/PowerShell time limit |\n\nAn unrecognised profile name fails closed to `readonly` with a warning on\nstderr, rather than guessing what you meant and possibly granting write access.\n\n## Tools\n\n<details>\n<summary><b>Screen</b> (5)</summary>\n\n| Tool | Tier | Description |\n|---|---|---|\n| `screen_list_monitors` | observe | Displays with position, resolution and DPI scale |\n| `screen_capture` | observe | Screenshot a monitor or the whole virtual desktop |\n| `screen_capture_region` | observe | Screenshot a rectangular region |\n| `screen_capture_window` | observe | Screenshot one window, even if overlapped |\n| `screen_list_capturable_windows` | observe | Windows available for individual capture |\n\n</details>\n\n<details>\n<summary><b>Windows</b> (7)</summary>\n\n| Tool | Tier | Description |\n|---|---|---|\n| `window_list` | observe | Visible top-level windows with stable ids and bounds |\n| `window_get_active` | observe | The window with keyboard focus |\n| `window_get_desktop_info` | observe | Virtual desktop bounds and cursor position |\n| `window_focus` | interact | Raise and focus a window, with verification |\n| `window_set_state` | interact | Minimize, maximize, restore, hide, show |\n| `window_move` | interact | Move and resize (un-maximizes first) |\n| `window_close` | interact | Ask a window to close |\n\n</details>\n\n<details>\n<summary><b>Input</b> (7)</summary>\n\n| Tool | Tier | Description |\n|---|---|---|\n| `input_move_mouse` | interact | Move the cursor |\n| `input_click` | interact | Click, right-click or double-click |\n| `input_drag` | interact | Drag between two points, interpolated |\n| `input_scroll` | interact | Scroll vertically or horizontally |\n| `input_type` | interact | Type Unicode text, or paste when long |\n| `input_press_keys` | interact | Chords such as `ctrl+shift+escape` |\n| `input_key_hold` | interact | Hold or release a key |\n\n</details>\n\n<details>\n<summary><b>UI Automation</b> (4)</summary>\n\n| Tool | Tier | Description |\n|---|---|---|\n| `uia_snapshot` | observe | Read an application's accessibility tree |\n| `uia_find` | observe | Find controls by name, id or type |\n| `uia_invoke` | interact | Click, toggle, expand, select or focus a control |\n| `uia_set_value` | interact | Set an editable control's text directly |\n\n</details>\n\n<details>\n<summary><b>System &amp; processes</b> (8)</summary>\n\n| Tool | Tier | Description |\n|---|---|---|\n| `system_info` | observe | OS, CPU, memory, disks, network, battery, GPU |\n| `system_list_services` | observe | Services with state and startup type |\n| `system_list_installed_apps` | observe | Installed applications |\n| `system_notify` | interact | Windows toast notification |\n| `system_control_service` | manage | Start, stop or restart a service |\n| `process_list` | observe | Processes with CPU and memory usage |\n| `process_start` | manage | Launch an application or open a document |\n| `process_kill` | manage | Terminate a process |\n\n</details>\n\n<details>\n<summary><b>Files, clipboard &amp; shell</b> (9)</summary>\n\n| Tool | Tier | Description |\n|---|---|---|\n| `file_known_folders` | observe | Standard Windows paths and current access limits |\n| `file_list` | observe | Directory listing with sizes and timestamps |\n| `file_read` | observe | Read text or base64 content |\n| `file_search` | observe | Find files by name pattern and content |\n| `file_write` | filesystem | Write, append or create |\n| `file_manage` | filesystem | Copy, move, delete, mkdir |\n| `clipboard_read` | observe | Read clipboard text |\n| `clipboard_write` | interact | Set clipboard text |\n| `shell_run` | shell | Run a PowerShell or cmd command |\n\n</details>\n\n**40 tools total.** Every one carries `title`, `readOnlyHint` and\n`destructiveHint` annotations.\n\n## Example\n\n> *\"Open Notepad, write my meeting notes into it and save to Documents.\"*\n\nClaude will typically:\n\n1. `process_start` → launch Notepad\n2. `window_list` → find the window and its **owning** process id\n3. `window_focus` → make sure keystrokes land there\n4. `input_type` → paste the notes via the clipboard\n5. `input_press_keys` `ctrl+s`, then `uia_set_value` on the filename field\n6. `screen_capture_window` → confirm the result visually\n\n## Safety\n\n- **Tier gating** is the primary boundary — disabled tools are never exposed.\n- **Path containment** resolves symlinks before checking, so a link inside an\n  allowed folder cannot reach a denied one. `System32`, `WinSxS`, `Boot` and the\n  Startup folder are refused in *every* profile, including `full`.\n- **Confirmation** via MCP elicitation before destructive actions.\n- **Audit log** of every call in JSONL, with sensitive-looking arguments\n  redacted. See [PRIVACY.md](PRIVACY.md).\n- **Modifier release** on shutdown, so a crash mid-chord cannot leave `Ctrl`\n  latched down.\n- **Refuses to terminate** its own process or pids 0–4.\n\nScreenshots capture whatever is on screen and send it to your AI provider.\nRead [PRIVACY.md](PRIVACY.md) before enabling screen capture on a machine that\nhandles confidential material.\n\n### Elevation\n\nWindows blocks a normal-privilege process from automating, capturing or sending\ninput to windows owned by **elevated** processes (UIPI). To drive an\nadministrator application, run the connector elevated — otherwise those calls\nfail with a clear explanation rather than silently doing nothing.\n\n## Privacy Policy\n\nWinCtl runs entirely on your machine. It has no backend, no telemetry and no\nanalytics, and it makes no network calls of its own. The author receives nothing\nabout you or your computer.\n\n- **What it accesses:** screen contents, window and application state, system and\n  process information, files within the folders you permit, and the clipboard —\n  each only when a tool is called. It generates synthetic input but never records\n  your real keyboard or mouse activity.\n- **Where data goes:** to the AI client you connect it to, and nowhere else.\n  Anything a tool returns becomes part of that conversation and is therefore\n  subject to that client's privacy policy. A screenshot sends whatever is on\n  screen to your AI provider — consider that before enabling screen capture on a\n  machine handling confidential material.\n- **What is stored:** only a local audit log at\n  `%LOCALAPPDATA%\\winctl\\audit.jsonl` — one line per tool call, with\n  sensitive-looking arguments redacted. It is never uploaded. Disable it with\n  `WINCTL_AUDIT_DISABLED=1`, or delete the file at any time.\n- **Retention and sharing:** nothing is retained off-machine and nothing is\n  shared with third parties.\n- **Contact:** Sitharaj Seenivasan — <sitharaj.info@gmail.com>\n\nFull policy: **[PRIVACY.md](PRIVACY.md)**\n\n## Development\n\n```bash\ngit clone https://github.com/sitharaj88/winctl\ncd winctl\nnpm install\nnpm run build\n\nnpm run smoke                 # self-test against the live desktop\nnode scripts/smoke.mjs --full # full MCP protocol suite, including UI Automation\nnpm run inspect               # MCP Inspector UI\n```\n\n`scripts/verify-interactive.mjs` drives Notepad end-to-end — it launches the\napp, types, verifies the text through UI Automation and cleans up. It uses the\nreal mouse and keyboard, so don't run it while you're using the machine.\n\n### Architecture\n\n```\nsrc/\n  index.ts              stdio entry point (DPI awareness runs first)\n  http.ts               streamable HTTP entry point, loopback-only by default\n  config.ts             profiles, tiers, limits\n  security/             tier definitions, path containment, audit log, errors\n  native/\n    ffi.ts              koffi bindings to user32/kernel32/dwmapi\n    dpi.ts              per-monitor DPI awareness\n    handles.ts          opaque, fingerprinted window ids\n    windows.ts          enumeration, focus, move, state\n    input.ts            SendInput mouse and keyboard\n    screen.ts           capture and token-aware encoding\n    powershell.ts       per-call PowerShell execution\n    uia.ts              UI Automation bridge\n  server/\n    registry.ts         tier gate + confirmation + audit in one place\n    createServer.ts     assembles tools, resources and prompts\n  tools/                the 40 tool definitions\n```\n\nTwo implementation notes worth knowing if you extend this:\n\n- **PowerShell runs one process per call.** A long-lived host sounds better, but\n  `-Command -` buffers all of stdin until the stream closes rather than\n  executing statement by statement, so it never returns a result. Per-call\n  processes also mean a hung script can't wedge later calls. Commands are passed\n  as `-EncodedCommand` (base64 UTF-16LE), which removes shell quoting as a\n  source of injection bugs.\n- **The `INPUT` struct size is asserted at startup.** A layout mismatch wouldn't\n  throw — it would send mouse events to garbage coordinates.\n\n## Publishing\n\n```bash\nnpm run build && npm publish --access public   # npm\nnpx @anthropic-ai/mcpb pack                    # build the .mcpb bundle\nmcp-publisher login github && mcp-publisher publish   # MCP registry\n```\n\nFor the Claude Connectors Directory, submit desktop extensions via\n[the extension form](https://clau.de/desktop-extention-submission).\n\n## Author\n\n**Sitharaj Seenivasan**\n\n- Website — [sitharaj.in](https://sitharaj.in)\n- GitHub — [@sitharaj88](https://github.com/sitharaj88)\n- LinkedIn — [in/sitharaj08](https://www.linkedin.com/in/sitharaj08)\n- Email — [sitharaj.info@gmail.com](mailto:sitharaj.info@gmail.com)\n\nIssues and feature requests are welcome at\n[github.com/sitharaj88/winctl/issues](https://github.com/sitharaj88/winctl/issues).\n\n## Licence\n\nMIT © [Sitharaj Seenivasan](https://sitharaj.in)\n",
  "bytes": 14834,
  "sha": "c86b3312a1fd3879ab41d11fe33cf8a0cd42a25ccc2102e7354219c24a06ecc6",
  "repo_slug": "sitharaj88/winctl",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sitharaj88_winctl_3b935e7c/readme"
}