# clawtouch-mcp

This MCP server lets an agent operate a physical keyboard and mouse through USB HID. It fits hardware test rigs, kiosks, and locked-down machines.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 13
- Author: tinqiao-oss
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/tinqiao-oss/clawtouch-mcp
- Updated: 2026-10-15
- HTML: https://affpapa.org/en/nevibecode/mcp/clawtouch-mcp

## What it does

\`clawtouch-mcp` is a standalone Python process that communicates over MCP on stdio. Its tools cover mouse clicks, text entry, scrolling, key combinations, and screenshots. The server sends those requests to a Raspberry Pi Pico 2 or another ClawTouch device, which presents the target system with ordinary USB HID input.

It can be added to Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and the other listed clients. The `--mock` mode runs without hardware and logs actions instead of moving anything. Screenshot support can be installed with `mss` and `Pillow`; macOS window operations require `pyobjc`.

Physical control requires a Raspberry Pi Pico 2 running ClawTouch HID firmware, or a ClawTouch box. For development and CI, use `clawtouch-mcp --mock --log-level INFO`; with hardware attached, the port can be set with `--port COM7` and the display size with `--screen 1920x1080`.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add clawtouch-mcp -- uvx clawtouch-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from clawtouch-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add clawtouch-mcp -- uvx clawtouch-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from clawtouch-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "clawtouch-mcp": {
            "command": "uvx",
            "args": [
                "clawtouch-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from clawtouch-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "clawtouch-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "clawtouch-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from clawtouch-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add clawtouch-mcp uvx clawtouch-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from clawtouch-mcp <command>

## When to use it
- send keyboard and mouse input as USB HID
- test software against genuine external input
- drive a separate machine in a test rig
- exercise MCP workflows without moving hardware

## Example prompts
- Use `device.info` to report the detected screen size and input device details.
- Click the requested coordinates, type the supplied text, and capture a screenshot.
- Run the workflow in `--mock` mode and log every action without touching the hardware.

## Similar
- [input-keyboard-mouse-touch](https://affpapa.org/en/nevibecode/skills/input-keyboard-mouse-touch.md) — skill · 946 installs
- [better-accessibility](https://affpapa.org/en/nevibecode/skills/better-accessibility.md) — skill · 29600 installs
- [wcag-audit-patterns](https://affpapa.org/en/nevibecode/skills/wcag-audit-patterns.md) — skill · 12486 installs
- [compose-focus-navigation](https://affpapa.org/en/nevibecode/skills/compose-focus-navigation.md) — skill · 1900 installs
- [antislop-human](https://affpapa.org/en/nevibecode/skills/antislop-human.md) — skill · 5900 installs
- [capacitor-keyboard](https://affpapa.org/en/nevibecode/skills/capacitor-keyboard.md) — skill · 1000 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md