Clawtouch MCP

English | 简体中文

clawtouch-mcp

Give your AI agent real hands.

An MCP server that turns any MCP-compatible client — Claude Desktop,

Cline, Continue,

Cursor, OpenClaw,

Hermes Agent and any other —

into something that can move a real mouse and press real keys through a USB HID device.

---

What is this?

A standalone Python process that speaks Model Context Protocol (MCP) over stdio and exposes mouse / keyboard primitives — hid.click, hid.type, hid.scroll, key combos, hid.screenshot — to whatever AI agent you already use. Under the hood it talks over USB serial to a ClawTouch HID device (a Raspberry Pi Pico 2 running the open ClawTouch HID firmware, or any turnkey ClawTouch box) and translates each tool call into a real USB HID report. The target OS sees a genuine physical keyboard and mouse — input arrives on the same driver path as any plugged-in peripheral, not as a software-injected synthetic event.

📦 MIT-licensed. No ClawTouch backend, no LLM, no agent loop on top —

just the raw HID plumbing so other agent stacks can talk to real hardware.

⚠️ This gives an agent real keyboard / mouse reach over a machine —

the same reach as a person at the keyboard. Read Safety first.

Why hardware HID?

Software automation (PyAutoGUI, OS-level input APIs, multimodal click-the-screen models) injects synthetic input events into a session — which requires an agent process running on the target machine, in that user session, with focus. A USB HID peripheral works the other way around: it emits real HID reports that travel the standard OS HID driver stack, exactly like a plugged-in keyboard or mouse. The OS recognizes the Pico natively as a standard USB HID class device and needs no mouse / keyboard driver and no HID agent process on the input side of the target. That difference is the whole point of this project — every other section below just builds on it.

The board acts on the machine it is plugged into. It takes its commands over the same USB cable it types through, so clawtouch-mcp runs on that machine too — the input side still needs no driver. The agent itself can run elsewhere; see Deployment modes.

Good for:

• Kiosks / locked-down machines — no input driver or input agent to install or keep running: the board is a standard USB keyboard and mouse (clawtouch-mcp itself runs on the machine).
• Accessibility — let a user drive their own computer via an agent issuing HID commands, without fighting per-app synthetic-input compatibility.
• Compatibility testing — verify your software handles *external* HID input correctly, which can differ from injected synthetic events.
• Test rigs — an agent on your dev laptop drives a test machine that runs clawtouch-mcp (started over SSH, for example — see Deployment modes).

Not for:

• Mass account creation / multi-account operations — a single-host tethered peripheral is structurally a poor fit; one device drives exactly one target, and to drive ten machines you buy ten devices.
• Application-specific scripted shortcuts (selectors, fixed-flow scripts for a particular site or app). Those belong in agent / RPA frameworks built on top of this primitive layer, not in this layer itself.

For standard desktop apps (browser, IDE, office suites) the software-only path is already enough — the hardware is just an extra option there, not a requirement. Its irreplaceable value is the cases above, where the input has to arrive as a genuine physical HID device with no input driver or input agent on the target. For the compliance boundary on the "not for" cases, see Acceptable use.

Quickstart

⚠️ Before you start: read Safety — a connected agent can operate this machine like a person at the keyboard.

Install

pip install clawtouch-mcp                     # minimal (serial only)

pip install 'clawtouch-mcp[screenshot]' # + mss + Pillow (JPEG, Retina resize) pip install 'clawtouch-mcp[screenshot-min]' # mss only — no native deps, works

under hardened-runtime hosts

pip install 'clawtouch-mcp[window]' # pyobjc — macOS needs it for

screen.windows; no-op elsewhere

Platform-specific setup guides (recommended on first install):

• Windows — docs/windows-setup.md: dual COM port enumeration, VS Code Claude extension .mcp.json config, full window restart required, display-scaling notes.
• macOS — docs/macos-setup.md: Keyboard Setup Assistant dialog on first plug-in, dual USB-CDC ports, Screen Recording permission, Pinyin IME punctuation gotchas.

Run

# 1. Auto-detect HID board AND auto-detect screen size (v0.2.3+)

clawtouch-mcp

2. Explicit port (Windows), screen still auto-detected

clawtouch-mcp --port COM7

3. Pin screen size manually (e.g. clamp to one monitor in a multi-monitor setup)

clawtouch-mcp --screen 1920x1080

4. No hardware — everything is logged, nothing moves (dev/CI mode)

clawtouch-mcp --mock --log-level INFO

v0.2.3+ auto-detects the primary monitor's physical pixel size on

startup so coordinates clamp to the actual screen rather than a

hard-coded 1920x1080. Use device.info from your MCP client to

see what was detected (screen.source is "detected" /

"explicit" / "unset").

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{

"mcpServers": { "clawtouch": { "command": "clawtouch-mcp", "args": ["--port", "COM7", "--screen", "1920x1080"] } } }

Restart Claude Desktop. You should see clawtouch show up in the MCP server list with 16 tools available (14 HID + 2 device; +2 if you pass --allow-screenshot, which enables hid.screenshot and screen.windows). Try:

Take a screenshot of my screen, find the search box, click it, and type

"hello world".

(Requires --allow-screenshot to enable the hid.screenshot tool — off by default for privacy.)

Other MCP clients

Copy-pasteable config for 7 verified clients (Claude Desktop / Code, Cursor, OpenClaw, Hermes Agent, ChatGPT Desktop / Codex CLI, Cherry Studio, Trae IDE) — see examples/integrations/INTEGRATIONS.md. PRs adding new clients welcome.

Deployment modes

*Is the agent on the same machine as the screen?* clawtouch-mcp covers the input side (agent tool call → HID report → real input), plus an opt-in hid.screenshot of the machine it runs on. What the agent does with the screen — reading it, deciding what to do next — is not in this repo.

Local mode — the common case. agent + clawtouch-mcp + Pico + the controlled screen all on one PC. hid.screenshot captures that same screen, so the visual feedback loop closes naturally; the Pico is a standard USB HID device needing no driver. Good for accessibility, single-machine RPA, compatibility testing, in-machine kiosk self-service.

Agent on another machine. The board takes its commands over its USB CDC data channel — the same cable that carries its keyboard and mouse — so it always acts on the machine it is plugged into, and clawtouch-mcp runs there. The agent can still run elsewhere: have your MCP client start clawtouch-mcp on the target machine through any transport it supports (an SSH command, for example). Keys, typing and relative mouse moves then work as they do locally. Absolute clicks and moves read the cursor position, and hid.screenshot reads the screen, so for those the server has to run inside the machine's logged-in desktop session — which a plain SSH login often is not: on Linux, set DISPLAY (and XAUTHORITY) for the desktop's X server; on Windows, OpenSSH sessions sit outside the interactive desktop, so start the server from within the session instead; on macOS it works once Screen Recording is granted (see macOS setup). What this firmware does not provide is a way to drive a machine that runs nothing at all: that would need a second command path to the board, which is not part of this repo.

Safety

Read this before connecting an autonomous agent. The runtime limits

above are flood / typo guards, not a security boundary against a

misbehaving agent.

Runtime safety limits

• Coordinates clamped to --screen WxH so an agent can't move the mouse to bogus pixel positions.
• Typed text capped at 4096 chars per call.
• hid.type is for ASCII / US-keyboard-layout text. Control characters (newline / tab / etc.) are stripped by default so an agent's multi-line draft isn't accidentally submitted — send Enter with hid.key("enter") and Tab with hid.key("tab"). Text containing anything outside ASCII (CJK, emoji, curly quotes) is refused before any of it is typed — the firmware would otherwise stop at the first such character with the text half entered; put that text on the clipboard and paste it instead.
• All operations rate-limited to --ops-per-sec (default 20). This counts *tool calls*, not individual HID reports — one call such as hid.drag or a long hid.type emits many reports, so the effective HID-report rate is higher. It is a flood / typo guard, not a security throttle.
• hid.screenshot is disabled unless you pass --allow-screenshot.
• hid.release_all exposed for use as a panic-stop tool from the agent.

What an agent connected to this can do

clawtouch-mcp turns your agent's tool calls into real USB HID input — the same property that makes the legitimate use cases work (kiosks, accessibility, compatibility testing, test rigs) carries a symmetric risk:

An autonomous agent connected here has, in practice, the same reach over the host as a person sitting at the keyboard. It can open any application, run commands in a terminal, install or remove software, and read, move, or delete files. Because the input arrives as ordinary HID, a confirmation prompt is not by itself a reliable barrier — treat any consent dialog as something the agent may act on. clawtouch-mcp does not inspect intent or content; it faithfully forwards each call to the hardware.

This can happen without you intending it, because the *agent* decides what to do. The usual triggers:

• Prompt injection. Untrusted text the agent reads off the screen, a web page, or an image ca