# Harusame64/desktop-touch-mcp [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/Harusame64/desktop-touch-mcp  
**GitHub Stars:** 23  
**npm Downloads (last month):** 3372  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/harusame64-desktop-touch-mcp

## Description
Windows desktop automation for LLM agents with entity-based actions instead of coordinate-only clicking. Uses UIA, CDP, screenshots, keyboard/mouse/clipboard, and terminal control, plus entity leases, verified delivery, causal context, and interaction memory to reduce silent UI automation failures.

## Tools
Capabilities this server exposes over MCP:

- **desktop_discover** — Observe the desktop. Returns interactive entities with leases (UIA, CDP, Terminal, Visual SoM).
- **desktop_act** — Perform actions (click, type, set a value, select) on entities via lease validation. Returns semantic diffs — plus an optional `roiCapture` (changed-region PNG + next-target preview) on visual-only targets.
- **desktop_state** — Lightweight check of focus, active window, cursor, and Auto-Perception attention signal.
- **screenshot** — Multi-mode capture: `detail='text'` (UIA/OCR), `diffMode` (P-frame), `dotByDot` (1:1), and `background`. Returns a cheap `screenshot://by-ref/{id}` link to the saved image instead of inlining pixels every time.
- **screenshot_query** — Inspect and prune the on-disk screenshot cache behind the by-ref links: `screenshot_query` lists saved captures without re-reading pixels; `screenshot_gc` reclaims space by retention policy (dry-run by default).
- **workspace_snapshot** — Instant session orientation: all window thumbnails + UI summaries in one call.
- **server_status** — Diagnostic check for native engine health and feature activation.
- **keyboard** — Send keyboard input. Supports background input (WM_CHAR) and IME-safe clipboard bypass.
- **mouse_click** — Precision coordinate-based interaction with homing and force-focus protection.
- **scroll** — Multi-strategy: `raw` (notches), `to_element`, `smart` (virtual lists), and `capture` (stitch).
- **click_element** — Legacy UIA-based click by name/ID (fallback when entities are unavailable).
- **browser_open** — Idempotent debug-mode launch and reliable navigation.
- **browser_click** — High-level DOM interaction stable across repaints and framework re-renders.
- **browser_eval** — Deep inspection via `js` (scripting), `dom` (HTML), and `appState` (SPA data extraction).
- **browser_overview** — Semantic discovery, grep-like DOM search, and pixel-accurate coordinate lookup.
- **terminal** — Unified command execution: `run` (send + wait + read), `read` (OCR/UIA), and `send`. `run` completion modes: `quiet`, `pattern`, and `exit` (waits for the command to finish + returns its exit code — see [Terminal command completion](docs/guide.md#terminal-command-completion-until)).
- **wait_until** — Efficient server-side polling for window, focus, text, or URL state changes.
- **window_dock** — Window management: `pin` (always-on-top), `unpin`, `dock` (corner snap), and `focus`.
- **workspace_launch** — Launch apps and auto-detect new HWNDs (supports localized titles).
- **run_macro** — Batch up to 50 operations into a single round-trip for maximum efficiency.
- **clipboard** — System-level text exchange and user alerts.
- **key_locker** — Manage credentials the terminal autofills for you (SSH key passphrases, sudo / login passwords). Secrets are entered once into the locker's own secure dialog and stored encrypted on this machine (Windows DPAPI); they are never shown to the assistant. `action='launch_console'` opens an autofill-capa…
- **excel** — Author and run Excel VBA macros via COM. `action='run_vba'` writes a macro into a managed Trusted Location and runs it; `action='check_access_vbom'` is a read-only preflight. Runs VBA where formula-only tools cannot. One-time setup: `node scripts/enable-access-vbom.mjs`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "desktop-touch-mcp": {
    "command": "npx",
    "args": ["-y","@harusame64/desktop-touch-mcp"]
  }
}
```

## Documentation

## What Harusame64/desktop-touch-mcp does

Harusame64/desktop-touch-mcp exposes Windows desktop operations through MCP. It can inspect windows and interactive controls, perform semantic actions such as clicking, typing, setting values, and selecting items, and report the resulting UI changes. It also supports direct keyboard and mouse input, screenshots, clipboard exchange, window placement, application launching, terminal commands, browser automation, Excel VBA execution, and credential autofill through its key locker.

The main interaction pattern is to call `desktop_discover`, receive entities identified through UI Automation, Chrome DevTools Protocol, terminal inspection, or visual detection, and then pass an entity lease to `desktop_act`. This avoids relying exclusively on screen coordinates. Actions include validation of the target window and can be refused with a reason when the intended input cannot safely reach its destination.

## How it works

A native Rust engine handles UI Automation and image-difference work when available. PowerShell provides a fallback path if the native component cannot be used. Visual-only applications can be inspected through OCR and Set-of-Marks output, which supplies numbered regions and click coordinates. Browser tools use DOM and application-state inspection in addition to pixel-based views.

Observation can be kept lightweight. `desktop_state` reports focus, the active window, cursor information, and an attention signal. `screenshot` supports text extraction, changed-frame capture, native-resolution capture, and background capture; saved images can be referenced through `screenshot://by-ref/{id}` links. `run_macro` batches up to 50 operations, and `wait_until` polls for window, focus, text, or URL changes.

Perception lenses can be registered for a window or browser tab. Passing a lens to action tools enables post-action perception feedback, helping the agent verify that the expected UI changed rather than taking another full screenshot after every operation.

## Setup and configuration

Run the package with Node.js using:

```bash
npx -y @harusame64/desktop-touch-mcp
```

The primary platform is 64-bit Windows 10 or 11. Node.js 20 or newer is recommended, and PowerShell 5.1 or newer is used for fallback execution. The launcher downloads and verifies the matching runtime release, then caches it under `%USERPROFILE%\\.desktop-touch-mcp`. Set `DESKTOP_TOUCH_MCP_HOME` to change that location, or use `DESKTOP_TOUCH_MCP_KEEP_RELEASES` to retain additional cached releases.

Add the command to an MCP client configuration. The repository specifically describes use with Claude, Cursor, and VS Code Copilot. A Visual C++ Redistributable may be needed for native input bindings. The key locker stores credentials locally with Windows DPAPI; its helper may trigger a SmartScreen or antivirus warning because it is unsigned.

## Tools and capabilities

- Discover entities and act on them with `desktop_discover` and `desktop_act`.
- Inspect focus, windows, screenshots, OCR, diffs, and cached captures.
- Send keyboard and mouse input, scroll, use the clipboard, and manage window focus or docking.
- Launch applications, execute terminal commands, wait for state changes, and batch operations.
- Open and inspect Chromium-based browsers through navigation, DOM, JavaScript, and app-state tools.
- Run Excel VBA macros after enabling VBOM access.
- Store terminal credentials in the encrypted key locker and use them for supported autofill flows.

## Limitations and notes

The server is designed primarily for Windows. macOS Apple Silicon support is a limited preview with four tools. Terminal typing in Windows Terminal requires asking the user each time and an MCP client with elicitation support. Excel VBA requires one-time VBOM access setup. An emergency stop is available by moving the mouse to within 10 pixels of the primary monitor's top-left corner for 500 milliseconds.

_Full upstream README: https://allmcps.com/mcp/harusame64-desktop-touch-mcp/readme_