Model Context Protocol · Pebble

Build Pebble watchfaces with an AI agent that can actually see the screen.

pebble-mcp gives Claude — or any MCP client — a real toolbox for the revived Pebble ecosystem: search the appstore, quantize art to the 64-color palette, plan fonts, convert SVG to PDC, and drive the emulator to build, install, and screenshot a watchapp end to end.

23 tools 4 resources 376 tests green emery · Pebble Time 2 pre-1.0 · not yet on PyPI
Sat Jul 1815:35
15:35
Protein 28 / 180 g
Calories 440 / 2400
DAY A
rendered & captured through pebble-mcp

What it does

Four capability tiers, degraded gracefully.

Each tier lights up only when its prerequisites are present, and capabilities() reports what's live. The pure-Python tiers run anywhere an MCP client runs — including phone and web hosts with no shell — so you can quantize your logo to Pebble colors from claude.ai with nothing installed locally.

Tier 1 · Appstore

Search, browse, compare, download

● always on — pure HTTPS

Query the live Pebble appstore, filter by emery compatibility, compare apps by hearts, and pull any app's .pbw straight into the emulator.

store_searchstore_app store_collectionstore_compare store_download_pbw
Tier 2 · Design

The 64-color world, mechanized

● on when Pillow is present

Quantize any image to the exact 2-bit palette, prep art for the watch screen / menu icon / appstore banner, find the nearest GColor, plan fonts, and validate SVG→PDC.

image_quantizeimage_prep color_nearestpalette_swatch font_planpdc_convert
Tier 3 · Dev loop

Build, install, drive, screenshot

◐ gated on the pebble CLI

Run whole screenshot flows against the emulator — one call returns metadata plus every frame as a viewable image — or step it manually with build, install, input, and log tools.

flow_runflow_validate pebble_buildpebble_install emu_screenshotemu_input emu_logsemu_startemu_stop
Tier 4 · Publish (planned)

Heart, publish, pin

◐ gated on an API token — coming in Phase 3

Authenticated actions against your own Rebble account: heart apps, publish a build with the new pebble publish, and push timeline pins — each behind an explicit confirmation.

store_heartpebble_publish timeline_push_pin

The signature trick

From a store listing to a screenshot gallery — of an app you didn't write.

01

Find it

store_search or an app id — filtered to what runs on your watch.

02

Fetch the binary

store_download_pbw pulls the .pbw the API points to.

03

Install & drive

A pbw flow step sideloads it and presses buttons — kill+wipe baked in.

04

See it

flow_run returns every frame as an image the model can read.

✓ Hubble by Logan Head — emery-compatible, 78 hearts · 1.7 MB pbw · 4 frames captured, 0 retries, 0 wedges — live astronomy math running in the emulator.

Where it stands

Real, tested, and honest about what's missing.

23
MCP tools
4
reference resources
376
tests, all green
~97
adversarial regression tests

Built on the official MCP Python SDK, stdlib-first so Tier 1 installs light. Two rounds of adversarial hardening closed real path-traversal escapes, decompression-bomb and download-size DoS vectors, and an import-time crash — every fix landed as a failing test first. The design tier already found and corrected a real bug in a shipping watchface (a mislabeled GColor).

Try it (once published)

Five lines of config. No server to host.

An MCP server is a small local program your client launches for you — not something you run or keep alive. Point any MCP client at it and the tools appear next to the built-ins. 

// .mcp.json — today, from a local checkout
{
  "mcpServers": {
    "pebble-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "path/to/pebble-mcp", "pebble-mcp"]
    }
  }
}

// after PyPI — the whole install is the config line
{ "mcpServers": { "pebble-mcp": { "command": "uvx", "args": ["pebble-mcp"] } } }

Before we ship

The pre-launch checklist.

Phase 1 (build) and Phase 2 (hardening) are done. What stands between here and uvx pebble-mcp working for a stranger: