earshot-relay MCP Server
OfficialEnables sending speech messages to the Earshot Android app on a phone and querying playback receipts, recent messages, and relay/device status through the MCP server.
Supports optional server-side speech synthesis through an OpenAI-compatible /audio/speech endpoint, allowing messages to be synthesized as audio instead of relying on the phone's Android text-to-speech.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@earshot-relay MCP Server tell my phone the build finished and all tests passed"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
missedand 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 202202 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 objectRetrying 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
| Text ( |
| The receipt: |
| Recent messages; relay, bucket and device state. |
| Checks configuration and the bucket write. |
| Where the phone reports what it did. This is what makes receipts possible. |
| An MCP server over streamable HTTP, same bearer token. A stdio mode is |
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 mcpThe 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
/healthzand the beacon URL needsAuthorization: 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:PutObjecton the channel prefixes. It never reads your bucket and never holds the phone's read key (docs/permissions.md).The default channel list is
phoneonly. The loudalarmchannel cannot be sent to unless you list it inEARSHOT_RELAY_CHANNELS, the MCPalarmtool exists only then, andalarmcan never be the default channel.What
alarmdoes 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
202means stored, not played.Not proof of attention:
finishedmeans 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 DockerDocs
API · Receipts · Server TTS · Tunnels · Permissions · MCP · Configuration · Examples
License: MIT, copyright AutomaticAI.
Available Tools
4 toolsreceiptARead-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
recentBRead-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
statusARead-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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Send and read WhatsApp, email and SMS from Claude, ChatGPT, Cursor or any MCP client, from your own accounts: your WhatsApp number (linked by QR code), your mailbox (IMAP/SMTP) and your Android phone (SMS from its SIM). Tools: list-accounts, get-account, add-account, add-email-account, list-messages, send-message (one channel or several in one call). Hosted, OAuth 2.1, nothing to install. Free plan with unlimited messages; paid plans from 19 EUR/month remove the footer and add media and webhooks. Docs and client configs: github.com/UnlimitedMessaging/unlimited-messaging-mcp
Phone, SMS and email for AI agents. One remote MCP endpoint, OAuth login, zero install.
Melaya is a remote MCP server. It gives an assistant hands on your own Android phone and browser: it reads the screen through the accessibility tree, then taps, types and navigates inside the apps and sites you allow-list, with no per-app API. It also builds, schedules and runs agent pipelines across 6k+ connected tools. OAuth 2.1, nothing to install.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP 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-
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and people to exchange direct messages, channels, push-to-talk, mail, SMS, searchable memory, and portable agent identities through a hosted MCP endpoint.1MIT

Hwip MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceLets 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 npmApache 2.0