win-computer-use

win-computer-use — operational guide for AI agents

You have access to the win-computer-use MCP server. It exposes 64 tools that let you drive a real Windows desktop: mouse, keyboard, screen capture, OCR, window/app management, files, HTTP, processes, audio, screen recording, macros, and a labeled on-screen virtual cursor. Tool names in this guide use the mcp__win-computer-use__ prefix that Claude clients see; other clients may strip it - apply the same prefix convention your client uses.

This file is the entry point. Detailed references are split into smaller files in references/ and loaded only when relevant.

TL;DR

1. You have a virtual cursor rendered as an always-on-top labeled overlay. Clicks default to Win32 PostMessage so the user's real cursor is not touched. Pass use_real_cursor: true when PostMessage won't work (Paint canvas, Chromium page bodies, games).
2. Tools return ok: true for "I dispatched the call", not "the effect happened". Always screenshot and verify for UI-changing actions whose effect you cannot predict.
3. The emergency hotkey may not be active in this install. Check emergency_stop_status().started on session start and warn the user if it is false.
4. OCR may be broken on the host (missing winrt-Windows.Globalization transitive dep). Have a hotkey/coord fallback ready.
5. Prefer direct tools over UI when you can: use write_text_file instead of typing into Notepad, http_get instead of driving a browser, clipboard_set instead of typing long text.
6. Don't toggle permission_set_bypass silently and don't close dirty docs without saving - close_window discards changes without prompting.

First-turn checklist

Run these in parallel at session start, then act on the results:

get_state()                  -> overlay alive? heartbeat fresh?
permission_status()          -> bypass on/off, what apps are allowed
emergency_stop_status()      -> if .started=false, WARN the user
emergency_resume()           -> clear stale stop flag from a prior session
list_monitors()              -> coord system and virtual desktop bounds
list_windows()               -> what is open; what to avoid touching
screenshot(monitor_index=1)  -> ground yourself visually