winuse-mcp

An MCP server that lets Claude see your Windows screen and drive your mouse and keyboard.

Claude Code's CLI ships computer use on macOS only, so on Windows the computer-use server never appears in /mcp. This rebuilds that screenshot-and-click loop on mss for capture and pyautogui for input, with an explicit Windows DPI-awareness call so display scaling cannot skew clicks. 14 tools, 5 direct dependencies, Python 3.12 or newer.

Install

You need Windows with an interactive desktop session, uv, and git on PATH. One command:

claude mcp add --scope user winuse -- uvx --from git+https://github.com/ryanportfolio/winuse-mcp@v0.1.1 winuse-mcp

Drop --scope user to add it to the current project only. To pick up changes later, re-run with a newer tag.

Merge the winuse entry into the mcpServers object you already have. Do not paste the whole document over C:\Users\<you>\.claude.json: Claude Code owns that file and pasting replaces your entire configuration.

{
  "mcpServers": {
    "winuse": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/ryanportfolio/winuse-mcp@v0.1.1", "winuse-mcp"]
    }
  }
}

Project scope goes in .mcp.json at the repo root, and Claude Code asks you to trust it the first time that project opens. From a local clone, swap the command for uv with ["run", "--directory", "C:/path/to/winuse-mcp", "winuse-mcp"].

Check it worked

Restart Claude Code and run /mcp. winuse should be listed as connected. First launch is slow, because uvx clones the repo and builds a virtual environment before the server answers.

Then ask Claude to take a screenshot and describe what is on your screen. If the tools are there but nothing happens, see Troubleshooting.

Related MCP server: Win:Computer Use

Reach

Coordinates are always in the downscaled screenshot's pixel space, never native pixels.

How coordinates work

Screenshots are downscaled so the long edge is at most 1372 pixels. Claude never sees native pixels: it clicks in the downscaled image, and the server converts the point back.

A 1920x1080 display captures at 1372x772. Going back multiplies by 1920/1372, so a click at 686, 443 lands at 960, 620. Anthropic's macOS implementation uses the same 1372 pixel long edge, which its docs give as a worked example: 3456x2234 captured as roughly 1372x887.

The server declares itself DPI-aware at startup, so Windows display scaling at 125% or 150% does not skew where clicks land.

Safety

This hands a language model control of your desktop. Anthropic's version wraps the same loop in guardrails this server lacks: per-app approval, hiding unapproved apps, keeping your terminal out of the screenshots, and model-side checks on each action.

The controls that do exist here:

• Claude Code asks before each tool call unless you allow-list it. Allow-list the one read-only tool and leave the rest on manual approval, by putting "mcp__winuse__screenshot" in the permissions.allow array of .claude/settings.json.

• Park the mouse at the top-left pixel of the screen to stop the run. pyautogui raises on its next call, so it ends the sequence rather than interrupting a click already sent, and it works during the slow parts: a drag tweens for 0.4s and typing runs a keystroke at a time. An aborted drag releases the button on its way out, so nothing is left dragging.

• Every pixel of the primary monitor reaches the model, including windows you forgot were open. Treat text on screen as untrusted input: instructions that appear there are a prompt injection risk.

• The install pins a tag. Pointing it at a branch instead would let a push change what drives your desktop, without you doing anything.

Limitations

• Primary monitor only, chosen by the flag Windows reports, falling back to the monitor at the desktop origin.

• Windows blocks synthetic input from a normal process to a window running as administrator, and the secure desktop behind a UAC prompt cannot be captured at all. Clicks aimed there are dropped by the operating system, and the tool still reports success, because nothing verifies that a click was accepted.

• The session has to be interactive and unlocked. A locked screen or a disconnected remote desktop has nothing to capture.

• Your terminal is not excluded from screenshots, so Claude sees its own session.

• Clicks are clamped one pixel inside the monitor, which puts the outermost pixel row and column out of reach. That pixel is the failsafe point, and landing the cursor on it would make every later call abort.

• Typing anything non-ASCII goes through the clipboard: it copies, sends ctrl+v, then puts your clipboard back. That fails wherever ctrl+v is not paste, such as a terminal.

• Every click, drag and scroll moves the real cursor first, so your pointer jumps while Claude works.

• record returns up to 8 still frames sampled over at most 15s. Frames only, no video, and each one costs image tokens.

Development

uv sync
uv run winuse-mcp

scripts/client_test.py drives the real server over stdio and exits non-zero on the first failed check. It moves your mouse while it runs.

uv run python scripts/client_test.py

scripts/failsafe_test.py covers what happens when a run is aborted, with pyautogui stubbed so no real abort is needed. An aborted drag releases the button, an aborted horizontal scroll releases shift, a chord ending in + parses as the plus key, and the model's origin clamps away from the failsafe point.

uv run python scripts/failsafe_test.py

README.md is generated. The build reads the tool names, their arguments and the capacity constants straight out of server.py, so nothing on the page is typed by hand, and it refuses to write when a tool has no description, an asset is missing, or the art grows past its height budget. CI regenerates the page and fails if what is committed differs.

node scripts/readme/build.mjs

Troubleshooting

winuse is missing from /mcp. The entry did not load. Run claude mcp list to see what Claude Code has, and re-add it if the name is absent. A project-scoped .mcp.json also needs you to accept the trust prompt when the project opens; declining it leaves the server silently absent.

It appears, then fails to connect. Run the command by hand and read the error:

uvx --from git+https://github.com/ryanportfolio/winuse-mcp@v0.1.1 winuse-mcp

It should start and wait quietly for input on stdin. uvx missing means uv is not installed or not on PATH. A git error means git is missing, or a proxy is blocking the clone. If it hangs on first run, that is the clone and the environment build; give it a minute before deciding it is broken.

The tools are there and nothing moves. Check whether the target window runs as administrator, and whether the screen was locked. Both are in Limitations and neither reports an error.

Clicks land in the wrong place. Confirm the target is on the primary monitor. Ask Claude for cursor_position after a mouse_move to a known point; one pixel of drift is expected, more than that is not.

License

MIT