Pebble Index 01 → Alexa bridge

Say "Tell Alexa to set an alarm for 5 minutes" into the ring, and your Echo sets the alarm.

How the pieces fit

Index 01 ring ──BLE──▶ Pebble app (transcribes) ──▶ Pebble cloud agent (LLM)
                                                          │  MCP tool call: tell_alexa("set an alarm for 5 minutes")
                                                          ▼
                               cloudflared tunnel ──▶ this server (server.py, Streamable HTTP MCP)
                                                          │  Alexa "text command" via aioamazondevices
                                                          ▼
                                                   your Echo (as if you had spoken it)

Why this shape:

• Pebble side. The Index 01 supports "bring your own MCP server", but only cloud-hosted servers over Streamable HTTP or SSE, and only Authorization-header auth (no OAuth). Custom MCP tools run in the double-click "MCP Sandbox" with the cloud agent; single click stays the offline note-taker.

• Alexa side. Amazon has no public "send a voice command" API. The workable route is the same unofficial endpoint Home Assistant's Alexa Devices integration uses (send_text_command), via the aioamazondevices library. Its own test script uses it to set a timer, so alarms/timers are the canonical case.

Related MCP server: alexa-mcp

Setup

1. Amazon prerequisite: app-based 2FA

The library logs in with email + password + a TOTP code. Your Amazon account must have an authenticator app (Google Authenticator, Authy, 1Password...) as its 2FA method. SMS-only 2FA does not work.

2. Install and log in once

cp .env.example .env
# fill in AMAZON_EMAIL, AMAZON_PASSWORD, and MCP_BEARER_TOKEN (openssl rand -hex 32)

uv sync
uv run alexa_login.py        # asks for your 6-digit authenticator code

It saves data/login_data.json and prints your Echo devices. Put the one you want (e.g. Kitchen Echo) in ALEXA_DEFAULT_DEVICE in .env.

3. Run the server

uv run server.py             # listens on 127.0.0.1:8765

Quick sanity check:

curl -s localhost:8765/healthz
curl -s -X POST localhost:8765/mcp \
  -H "Authorization: Bearer $MCP_BEARER_TOKEN" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

4. Expose it publicly with cloudflared

For a quick test (URL changes each run):

cloudflared tunnel --url http://localhost:8765

For something permanent, make a named tunnel on a hostname you own, e.g. alexa.example.com:

cloudflared tunnel login
cloudflared tunnel create alexa-bridge
cloudflared tunnel route dns alexa-bridge alexa.example.com
cat > ~/.cloudflared/config.yml <<EOF
tunnel: alexa-bridge
credentials-file: $HOME/.cloudflared/<TUNNEL-UUID>.json
ingress:
  - hostname: alexa.example.com
    service: http://localhost:8765
  - service: http_status:404
EOF
cloudflared tunnel run alexa-bridge

systemd/ has user units to keep both the server and the tunnel running.

5. Add it to the Pebble app

In the Pebble app, Index tab → MCP & Tool Settings:

1. Create a sandbox group. Model: Default (bump to High Capability only if it picks tools unreliably).

2. MCP Servers tab → add server:

   • Name: alexa

   • URL: https://<your-public-host>/mcp (or /alexa/mcp when served under the BASE_PATH prefix; see DEPLOY.md for our setup)

   • Type: Streamable

   • Authorization: Bearer <your MCP_BEARER_TOKEN> — the word Bearer is required

   • Group: the sandbox group from step 1

3. Index settings → "Double click and hold" → assign that sandbox group.

Now: double-click-and-hold the ring, say "Tell Alexa to set an alarm for 5 minutes", release. The cloud agent calls tell_alexa, and you get a phone notification with the tool result.

Gotcha from the community: the app caches the tool list for ~30 s after a config change. If tools don't show up, toggle the transport SSE → Streamable to force a refetch.

Tools exposed

Caveats

• Unofficial Amazon API. It is the same one Home Assistant's core Alexa Devices integration relies on, so it is well exercised, but Amazon can change it. If calls start failing with auth errors, rerun alexa_login.py.

• Cloud dependency. Custom MCP tools only run through Pebble's cloud agent, so the transcript of the double-click request leaves your phone. Single-click notes still stay local.

• Alarms land on the Echo, not on the ring or phone. That is the point here, but the "device" argument lets you aim at a different Echo ("...on the bedroom echo").

• Amazon Japan uses a different login flow and is not supported by the library.

Alternatives considered

• Home Assistant as the gateway. If you already run HA, its Alexa Devices integration plus the MCP Server integration could replace this repo: expose an HA script that calls alexa_devices.send_text_command to Assist, and point Pebble at https://<ha>/api/mcp/assist with a long-lived access token. More moving parts if you don't already have HA.

• Alexa Routine triggered by a virtual sensor. Routines can run a "custom" command as an action, but the text is fixed at routine-creation time, so "5 minutes" can't be dynamic. Dead end for this use case.

• Alexa Voice Service. Would create alarms on a virtual device, not your Echo.

• Pebble webhook instead of MCP. The Index can POST the raw transcription to a URL. That would work too, but you'd have to parse "tell alexa to ..." yourself and it fires for every recording on that button. MCP lets the agent decide when Alexa is meant.

License

MIT, see LICENSE.