tinqiao-oss/clawtouch-mcp

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
**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
> 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