cardputer-claude-mcp

English | 中文

Turn an M5Stack Cardputer-Adv
into a physical control surface for an AI coding agent.

A small MicroPython app on the handheld talks over BLE to a Mac-side MCP
bridge, so an agent (Claude Code, etc.) can:

• notify / ask / confirm — push banners, multiple-choice questions, and
  physically-confirmed approvals to the device,
• usage — show a live, always-on dashboard (today's spend + 5h/7d
  subscription utilization + battery) with a resident pixel-crab mascot,
• gate the shell — a Claude Code hook routes Bash commands and file
  edits to the device for approval before they run.

The headline trick is the approval gate: routine commands pass through a
whitelist, ordinary ones take a single Enter on the device, and
destructive ones (rm -rf, git push, sudo, edits to secrets) take a
single Y press — a different key from the ordinary prompt's Enter, and a
physical keypress that prompt-injection can't synthesize. If the device is
away, it falls back to the normal terminal prompt — the Cardputer is an
optional gate, never a dependency.

Ordinary action — press Enter	Destructive action — press Y

Layout

device/cardputer_mcp.py   MicroPython app: BLE GATT service, idle dashboard,
                          mascot animation, notify/ask/confirm/usage screens
mcp/server.py             Mac bridge: BLE owner + MCP tools + usage monitor +
                          the /hook/confirm route for the approval gate
mcp/auth.py               bearer-token auth for the HTTP transport
mac/                      launchd bridge daemon + the PreToolUse approval hook
mac/README.md             how to install & tune the Mac side  ← start here

Quick start

1. Bridge: cd mcp && python3 -m venv .venv && .venv/bin/pip install -r requirements.txt,
   then run mac/install_cardputer_bridge.sh (see mac/README.md).
2. Device: device/cardputer_mcp.py is not standalone — it deploys
   into the cardputer-claude-os
   UIFlow launcher bundle, which provides the app menu, NimBLE bring-up, and
   the matrix-keyboard driver that this app's run() relies on. Compile it to
   .mpy (matching mpy-cross), drop it into that bundle's /flash/apps/,
   and delete the .py (importing the source form OOM-crashes the launcher).
   This repo intentionally ships only the app, not that launcher framework.
3. Approval gate: register mac/adv_confirm_hook.py as a PreToolUse
   hook in ~/.claude/settings.json (snippet in mac/README.md).

Hardware notes (Cardputer-Adv)

• Audio is an ES8311 codec + NS4150B amp. M5.Speaker.tone() only sounds
  if the app's main loop calls M5.update() every iteration — without it
  the chirps are silent. The speaker amp is also muted while the 3.5 mm jack
  is engaged.
• The device app must be deployed as compiled .mpy, not source.

Security

The bridge gates every HTTP request behind a bearer token; tokens live only
in ~/.config/cardputer-bridge/env (never committed). A physical Y press on
the device is the trust anchor for irreversible operations.

Acknowledgements

• Built on cardputer-claude-os — the Cardputer ↔ Claude BLE bundle this extends.
• Usage dashboard inspired by cardputer-claude-usage.
• Spend / token figures come from ccusage.

License

MIT © 2026 neu