Skip to main content
Glama
earshot-relay MCP Server

earshot-relay MCP Server

Official

earshot-relay

A small self-hosted service that lets scripts, CI jobs and AI agents send speech to your phone. You POST text (or an audio file) to the relay, it drops an object into your own S3-compatible bucket, and the Earshot Android app, when it is listening to that bucket, plays it out loud. The relay also records what the phone reported doing with each message, so you can ask for a receipt.

Put thing in bucket. Hear it on phone. The relay is the "put thing in bucket" part, behind one HTTPS endpoint, a CLI and an MCP server.

Before you start

  • The Earshot app on the phone, already listening to your bucket (the buyer guide covers that). Text messages are spoken by the phone's Android text-to-speech, which needs Earshot 0.1.11 or newer and a TTS voice installed on the phone (Settings, System, Languages, Text-to-speech output). Audio files need neither.

  • Normal channels play at the phone's media volume and wait while the phone is on a call; a message older than the app's freshness limit (30 minutes by default) is reported as missed and not played.

  • A writer key for the same bucket that can PutObject (minimal permissions). Not the phone's key.

Related MCP server: phone-mcp

Run it

The image is ghcr.io/automaticai-io/earshot-relay (linux/amd64 and linux/arm64, so a Raspberry Pi works):

curl -fsSLO https://raw.githubusercontent.com/AutomaticAI-io/earshot-relay/main/.env.example && mv .env.example .env
docker run --rm ghcr.io/automaticai-io/earshot-relay token    # prints a random token for EARSHOT_RELAY_TOKEN
# fill in .env: the bucket, the writer key and that token
docker run -d --name earshot-relay --restart unless-stopped \
  --env-file .env -p 127.0.0.1:8080:8080 -v earshot-relay-data:/data \
  ghcr.io/automaticai-io/earshot-relay
docker exec earshot-relay earshot-relay doctor     # checks the relay and writes one inert test object

:latest is the newest release, :1 follows 1.x, and :edge is the tip of main. With compose, docker compose up -d uses the same image; docker compose up -d --build builds this checkout instead.

The relay refuses to start while .env still holds the example placeholders or an empty token. Without Docker: uv sync, then uv run earshot-relay serve with the same environment variables (put them in your shell, or set -a; . ./.env; set +a).

60-second demo

export EARSHOT_API_URL=http://127.0.0.1:8080
export EARSHOT_API_TOKEN=...        # the EARSHOT_RELAY_TOKEN you set

curl -fsS -X POST "$EARSHOT_API_URL/v1/messages" \
  -H "Authorization: Bearer $EARSHOT_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"text": "Build finished. All tests passed."}'
# {"id":"msg_...","status":"stored","channel":"phone","key":"phone/....say",...}   <- HTTP 202

202 means the message is stored in the bucket. If the phone is listening, it should speak it within a few seconds. Then ask what the phone did (needs receipts set up):

curl -fsS "$EARSHOT_API_URL/v1/messages/latest?wait=30" -H "Authorization: Bearer $EARSHOT_API_TOKEN"

Nothing played? Check the app's Last 20 items list on the phone (a failed .say row names the cause, such as a missing TTS voice), the media volume, and the receipt's hint.

Or use the CLI. In the container it is already installed (docker exec earshot-relay earshot-relay say "hello"); from a checkout, run it as uv run earshot-relay ..., or install it on your PATH with uv tool install .:

earshot-relay say "Deploy is done"
earshot-relay drop ding.mp3
earshot-relay receipt latest --wait 30     # exit 0 finished, 3 not played on any reporting device, 4 timed out
earshot-relay doctor                       # checks the relay and writes one inert test object

Retrying a send? Pass an Idempotency-Key header (CLI: --idempotency-key): the same key within 24 hours returns the first result instead of playing twice.

What it does

POST /v1/messages

Text ({"text": ...}) or an audio file (multipart). Returns 202 once the object is in the bucket. Optional Idempotency-Key header.

GET /v1/messages/{id}

The receipt: stored, detected, started, finished, skipped, failed, missed or unconfirmed, with a timeline. ?wait=30 long-polls.

GET /v1/messages, GET /v1/status

Recent messages; relay, bucket and device state.

POST /v1/doctor

Checks configuration and the bucket write.

POST /v1/beacons/{token}

Where the phone reports what it did. This is what makes receipts possible.

/mcp

An MCP server over streamable HTTP, same bearer token. A stdio mode is earshot-relay mcp.

The full contract is openapi.yaml; a readable version is docs/api.md.

Speech

By default the text goes to the bucket as a .say object and the phone's own Android text-to-speech speaks it. Optionally point the relay at any OpenAI-compatible /audio/speech server and it will synthesize audio itself ("speech": "server"), with a 700 ms lead-in so the start of the sentence is not swallowed. See docs/tts.md. A server TTS failure returns an error; it never silently falls back to the phone's voice.

Claude Code, Codex and other agents

claude mcp add --transport http earshot https://your-relay.example.com/mcp \
  --header "Authorization: Bearer $EARSHOT_API_TOKEN"

claude mcp add earshot --env EARSHOT_API_URL=http://127.0.0.1:8080 \
  --env EARSHOT_API_TOKEN=$EARSHOT_API_TOKEN -- earshot-relay mcp

The first form talks to a running relay over HTTP; the second runs a local stdio server, which needs earshot-relay on your PATH: install it once with uv tool install /absolute/path/to/earshot-relay (Claude Code starts the server from your project directory, so a relative path such as uvx --from . does not work). Tools: say, receipt, recent, status, plus alarm only if you enabled that channel. See docs/mcp.md.

For agent hooks (speak when Claude Code needs you, or when it finishes), see examples/ and read the warning there: hook examples send a slice of agent text to your bucket, so use a private bucket.

Receipts and the beacon URL

The phone can report detected, started and finished to an HTTPS endpoint you choose. Set EARSHOT_RELAY_BEACON_TOKEN and EARSHOT_RELAY_PUBLIC_URL, run earshot-relay status, and paste the printed https://<host>/v1/beacons/<token> into the app's Optional HTTPS beacon endpoint. The phone must be able to reach that URL, which usually means a tunnel: docs/tunnels.md covers Tailscale serve and Cloudflare Tunnel.

A receipt records what the phone did (device playback). It is not proof that a person heard the message, and the relay never words it that way. Details and edge cases: docs/receipts.md.

Security notes

  • Every endpoint except /healthz and the beacon URL needs Authorization: Bearer <EARSHOT_RELAY_TOKEN>. The beacon URL carries its own, different token in the path; it can record receipts but cannot send messages.

  • The relay needs only s3:PutObject on the channel prefixes. It never reads your bucket and never holds the phone's read key (docs/permissions.md).

  • The default channel list is phone only. The loud alarm channel cannot be sent to unless you list it in EARSHOT_RELAY_CHANNELS, the MCP alarm tool exists only then, and alarm can never be the default channel.

  • What alarm does on the phone: a siren, then the message on the alarm stream at high volume, ahead of normal items. It plays during a phone call (unless the app's Alarms can interrupt calls is off) and the other party may hear it. Do Not Disturb set to "Total silence", an Android refusal, a stopped service, a powered-off phone, battery restrictions or no network can still silence it. It is not an emergency or life-safety service.

  • Message text is not stored in the relay's database and is not logged. Tokens are never logged. Secrets can be supplied as files (EARSHOT_RELAY_TOKEN_FILE, ...).

  • Bind to localhost (the compose file does) and put a tunnel or an HTTPS reverse proxy in front. Do not expose the plain-HTTP port to the internet.

  • The beacon route has its own rate limit (EARSHOT_RELAY_BEACON_RATE_LIMIT, 600 per minute) and accepts at most 16 devices per message, so a leaked beacon URL can forge receipts but cannot flood the relay.

  • Messages sit in your bucket as plain objects. Anyone who can read the bucket can read them.

  • Rate limits (60 per minute overall, 6 per hour for the alarm channel) are in memory and per process.

What it is not

  • Not a hosted service: you run it, with your bucket.

  • Not a speech-to-text or chat product, and not a delivery guarantee. The phone has to be on, online, listening and allowed to play audio; a 202 means stored, not played.

  • Not proof of attention: finished means the phone finished playback.

  • Not a way to read your bucket or list your files.

  • Not affiliated with any cloud provider. "Earshot" is the name of the Android app; this project's MIT license covers this code only and grants no trademark rights.

Development

uv sync
uv run pytest -q                              # moto-backed; no network or real bucket needed
uv run python scripts/gen_openapi.py          # regenerate openapi.yaml after API changes
uv run python scripts/docker_smoke.py         # build the image and test it end to end against moto (Docker)
EARSHOT_COMPAT_PROVIDERS=1 uv run pytest -q tests/test_providers.py   # SeaweedFS and Garage in Docker

Docs

API · Receipts · Server TTS · Tunnels · Permissions · MCP · Configuration · Examples

License: MIT, copyright AutomaticAI.

Available Tools

4 tools
receiptA
Read-only

Did the phone play it? Returns the device-playback receipt of a message (id from say or alarm, or 'latest'): stored, detected, started, finished, skipped (the user skipped it), failed, missed (not played: it went stale, the bucket changed or audio was unavailable) or unconfirmed (no device report yet). wait_seconds (0-60) waits for a final status; final says whether waiting longer could still change it. A finished receipt means the phone finished playing it, not that a person heard it.

Inputs: id, wait_seconds. Returns: object

recentB
Read-only

List recent messages sent through this relay with their playback status (newest first).

Inputs: limit, channel. Returns: object

sayA

Send a short message to be spoken aloud on the user's phone through Earshot. The text is stored in the user's bucket; if the Earshot app is listening it should speak it within seconds (Android text-to-speech by default, at the phone's media volume; held while the phone is on a call). A successful call means stored, not played. Keep it to one or two plain sentences. Returns the message id; call receipt with it to learn whether the phone played it. Not for the alarm channel: urgent alerts use the alarm tool, which exists only when the user enabled it.

Inputs: text (required), voice, speech, channel. Returns: object

statusA
Read-only

Relay status: sendable channels, speech modes, and the last beacon from each phone.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool has a distinct role: say sends, receipt checks a specific message's playback, recent lists history, and status reports relay state. The main confusion is that say's description points to an 'alarm tool' for urgent alerts that does not exist in this tool set, and receipt's status vocabulary overlaps with recent's playback status listing.

    Naming Consistency3/5

    All names are single lowercase words, which is at least consistent in style, but the parts of speech vary (verb 'say' vs. nouns 'receipt'/'status' vs. adjective 'recent'). There is no predictable verb_noun pattern that would help an agent infer new tool names.

    Tool Count4/5

    Four tools is a tight, well-scoped set for a message relay: send, verify, list, and health. It is on the thin side, and the missing alarm channel referenced in descriptions suggests the surface was trimmed.

    Completeness2/5

    The say description explicitly defers urgent alerts to an 'alarm tool' that is absent, creating a dead end for the server's stated urgent-use case. There is also no way to cancel a message, inspect bucket contents, or manage which phones are registered, leaving only the happy path covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for a local-first messaging workspace that integrates Google Messages, WhatsApp, and Signal. It enables reading, sending, searching messages, and managing conversations through MCP tools.
      73
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables desktop agents such as Claude Code and Codex to control an Android phone as a long-lived action endpoint, pairing over outbound WebSocket and exposing phone capabilities as MCP tools with local pause and revocation.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets an agent ask the user a question that lands on their phone and returns the reply inside the same tool call, plus send one-way notifications, clipboard text, files, and channel broadcasts. Works with Claude Code, Cursor, Windsurf, Gemini CLI, and any MCP client.
      220 npm
      Apache 2.0