pebble-mcp

<p align="center"> <img src="https://raw.githubusercontent.com/dbonomo/pebble-mcp/master/docs/demo.gif" alt="pebble-mcp downloading a store app and screenshotting it in the emulator" width="200"> </p>

An MCP server for the Pebble smartwatch ecosystem: appstore search, a 64-color design toolkit, and the local dev loop (build → emulator → screenshot flows) exposed as typed tools usable from any MCP host — Claude Code, Claude Desktop, claude.ai, or any other agent — not just a shell. The demo above is a single flow_run: it installs a real appstore app (Hubble) onto the emery emulator, drives the buttons, and captures each screen — all through MCP.

Install

Once published to PyPI, no checkout is needed — uvx runs it on demand. Add this to your MCP host's config (e.g. a Claude Code .mcp.json):

{
  "mcpServers": {
    "pebble-mcp": {
      "command": "uvx",
      "args": ["pebble-mcp"]
    }
  }
}

To run from a local checkout instead (development, or before the PyPI release):

{
  "mcpServers": {
    "pebble-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/pebble-mcp", "pebble-mcp"]
    }
  }
}

Quickstart (Claude Code)

# from PyPI (once published)
claude mcp add pebble-mcp -- uvx pebble-mcp

# or from a local checkout
claude mcp add pebble-mcp -- uv run --directory /absolute/path/to/pebble-mcp pebble-mcp

Then, in a session, ask the agent to call capabilities() to see which tiers are live, or store_search("weather") to hit the appstore immediately.

Capability tiers

The server registers tools in four tiers and probes the environment at startup, so an agent only ever sees the tools it can actually run.

• Tier 1 — Appstore (pure HTTPS, no auth, always on): store_search, store_app, store_collection, store_category, store_developer, store_compare, store_download_pbw.
• Tier 2 — Design toolkit (pure Python + Pillow): color_nearest, palette_swatch, image_quantize, image_prep, font_plan, pdc_convert. Pillow is a core dependency, so this tier is normally always on; capabilities() still probes for it and degrades gracefully if it is somehow absent.
• Tier 3 — Dev loop (requires the pebble CLI on PATH): pebble_build, pebble_install, emu_start, emu_stop, emu_screenshot, emu_input, emu_logs, flow_validate, and the crown jewel flow_run — run a gallery-style flow spec and get every screenshot back as MCP images. These tools register only when pebble is found.
• Tier 4 — Authenticated (requires PEBBLE_API_TOKEN; off by default): reserved for token-gated, network-mutating operations (heart an app, publish, timeline pins). Detected by capabilities(); opt-in only.

Read-only reference is also exposed as MCP resources: pebble://colors, pebble://fonts, pebble://platforms, pebble://wire-conventions.

The capabilities() tier probe

Call the capabilities() tool first. It reports which tiers are live in the running environment (tier1_appstore, tier2_design, tier3_devloop, tier4_auth) so an agent can plan its work instead of calling a tool that isn't wired up. Tier 1 is always true; the rest reflect Pillow, the pebble CLI, and PEBBLE_API_TOKEN respectively.

Development

uv sync            # install deps (+ dev group: pytest, ruff)
uv run pytest      # run the test suite
uv run ruff check  # lint

The pebble_mcp/examples/flows/ directory holds sample flow specs (used by the tests and as living documentation of the flow format, including the # SAFETY RULES (live-write hazards — DO NOT TRIGGER): convention that flow authors should follow for any app with server-mutating screens).

License

MIT — see LICENSE. Copyright (c) 2026 Daniel Bonomo.

---

Not affiliated with, endorsed by, or sponsored by Core Devices or Rebble. "Pebble" and related marks belong to their respective owners.