clawtouch-mcp

<!-- mcp-name: io.github.tinqiao-oss/clawtouch-mcp -->

**English** | [简体中文](README.zh-CN.md)

# clawtouch-mcp

> **Give your AI agent real hands.**
> An MCP server that turns any MCP-compatible client — [Claude Desktop](https://claude.ai/download),
> [Cline](https://github.com/cline/cline), [Continue](https://github.com/continuedev/continue),
> [Cursor](https://www.cursor.com/), [OpenClaw](https://github.com/openclaw/openclaw),
> [Hermes Agent](https://github.com/NousResearch/hermes-agent) and any other —
> into something that can move a real mouse and press real keys through a USB HID device.

[![PyPI version](https://img.shields.io/pypi/v/clawtouch-mcp.svg)](https://pypi.org/project/clawtouch-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/clawtouch-mcp.svg)](https://pypi.org/project/clawtouch-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Commercial: clawtouch.cn](https://img.shields.io/badge/commercial-clawtouch.cn-orange.svg)](https://clawtouch.cn)
[![clawtouch-mcp MCP server](https://glama.ai/mcp/servers/tinqiao-oss/clawtouch-mcp/badges/score.svg)](https://glama.ai/mcp/servers/tinqiao-oss/clawtouch-mcp)

<p align="center">
  <img src="https://raw.githubusercontent.com/tinqiao-oss/clawtouch-mcp/master/docs/assets/hero.png" alt="clawtouch-mcp data flow: an AI agent sends MCP tool calls over stdio JSON-RPC to clawtouch-mcp, which forwards framed bytes over USB-CDC to a Raspberry Pi Pico 2 running ClawTouch HID firmware, which emits standard USB HID reports to the target OS (Windows / macOS / Linux)." width="900">
</p>

---

## 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](#hardware), 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](#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](#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](#acceptable-use).

## Quickstart

> ⚠️ Before you start: read [Safety](#safety) — a connected agent can operate this machine like a person at the keyboard.

### Install

```bash
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`](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`](docs/macos-setup.md): Keyboard
  Setup Assistant dialog on first plug-in, dual USB-CDC ports, Screen
  Recording permission, Pinyin IME punctuation gotchas.

### Run

```bash
# 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):

```json
{
  "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`](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](docs/macos-setup.md)). 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.
* Typ