Skip to main content
Glama

Beep Me lets every AI agent you run message you and read your answer. Messages go out as a text, a Telegram message, an email, a Slack or Discord post, or a phone push. Beep Me is one remote MCP (Model Context Protocol) server on Cloudflare Workers. You set it up and manage it from your phone.

  • All agents use one URL. This includes Claude on the web, desktop, and mobile, Claude Code, and other MCP clients. Scripts, cron jobs, and continuous integration (CI) use a REST endpoint.

  • Agents can ask you a question with choices, or ask for a written answer, and read what you sent back with the get_replies tool or GET /v1/replies. They can attach screenshots, logs, and other files, and set a sender name such as a project name.

  • You sign in with Google, so there is no password to manage. The dashboard works on a phone, and you can add it to your home screen.

  • You connect your own accounts and keys. Beep Me sends through Telegram, Twilio and Telnyx text messages (SMS and MMS), Resend, Gmail, SMTP, Slack, Discord, ntfy, Pushover, and webhooks. Telegram has a main chat and a thread for each topic. Each channel has a Test button.

  • Priority decides where a message goes. High and urgent go out as a text message, medium goes to your Telegram chat, and low goes to the topic's thread. A new topic gets its own thread the first time an agent uses it.

  • Rules route or mute messages by priority, topic, and agent. During quiet hours, Beep Me skips texts and delivers without sound. Urgent messages still break through. Each agent has a text cap and a message cap. Beep Me collapses repeated messages into one message.

  • For each agent, you pick the channels it can use and the highest priority it can send. When you revoke an agent from your phone, its next call fails.

  • The delivery log shows which agent sent each message, where it went, and whether it arrived. Text messages include the provider's delivery receipt. Open a message to see its answers and files.

Where you can answer

Where

How

Telegram

Tap a choice button, reply to the message, or send text, a photo, a file, or a voice note. Emoji reactions count too.

Text message (Telnyx, Twilio)

Text back a choice's number or text, or just write an answer. Photos come through as files.

Email (Resend)

Each agent sends from its own address on your domain. Reply to the email to answer.

ntfy

Tap a choice button, for questions with up to 3 options.

Dashboard

Open the message and pick a choice or write an answer. Slack, Discord, Pushover, Gmail, and SMTP messages link to it.

Guided setup in the dashboard

  • Telnyx: paste an API key and Beep Me lists your numbers. The setup panel checks the messaging profile, the reply webhook, the public key, and US registration (10DLC brand and campaign, or toll-free verification). It can create a profile, send replies to Beep Me, and assign the number to one of your 10DLC campaigns.

  • Resend: pick a domain you already have in Resend or add a new one. Beep Me shows the DNS records to add, as a zone file when Cloudflare serves the domain. It can turn on receiving and create the reply webhook.

Nothing changes in your Telnyx or Resend account until you confirm it. Beep Me shows you each change first.

Deploy in about 3 minutes

You need Node.js 24 or later, Bun 1.2 or later, a Cloudflare account, and a Google account.

git clone https://github.com/yannelli/beep-me.git && cd beep-me
bun install
bun run setup

The setup script shows each step before it changes anything. It does these steps:

  1. Signs you in to Cloudflare and picks the account.

  2. Creates or finds the D1 database and the KV (key-value) namespace. Saves their IDs in .beep-me/deploy.json, which Git ignores.

  3. Asks which Google accounts can sign in.

  4. Keeps the workers.dev address, or puts Beep Me on a hostname in one of your Cloudflare zones.

  5. Builds and deploys the Worker with a new random APP_SECRET.

  6. Shows the redirect URI for your Google OAuth client. Saves the client ID and the client secret.

Run bun run setup --dry-run to see the plan first. In CI or from an agent, pass the inputs as flags: bun run setup --yes --account-id <id> --emails you@example.com. Missing inputs exit with code 2.

Manage the deployment with bun run cli. With no command it opens a menu. The commands are status, agents, channels, messages, pause, resume, emails, google, domain, deploy, logs, open, connect, upgrade, and teardown. bun run cli domain moves Beep Me to a hostname in one of your Cloudflare zones, adds alias hostnames, or goes back to workers.dev. Pass --yes to run a command without questions, or --dry-run to print each change first. bun run cli <command> --help shows the flags of one command. Each deployment documents the CLI at /docs/reference/cli.

To update, run bun run upgrade. It moves your copy to the newest release and deploys it. Copies before v0.6.0 do not have this command. Run this line once in the Beep Me folder instead:

curl -fsSL https://raw.githubusercontent.com/yannelli/beep-me/main/scripts/upgrade.sh | bash

Each deployment documents updates at /docs/updating.

Then do these steps on your phone:

  1. Open the Worker URL.

  2. Sign in with Google.

  3. Connect a channel.

  4. Press Test.

bunx wrangler d1 create beep-me                   # note the database_id
bunx wrangler kv namespace create beep-me-oauth   # note the id
mkdir -p .beep-me && cat > .beep-me/deploy.json <<'JSON'
{ "databaseId": "<database_id>", "kvNamespaceId": "<id>", "allowedEmails": "you@example.com" }
JSON
bun run deploy
openssl rand -hex 32 | bunx wrangler secret put APP_SECRET

Until APP_SECRET is set, the Worker shows a setup page. Create a Google OAuth client at https://console.cloud.google.com/auth/clients/create (type: Web application). Add the redirect URI https://<your-worker>/auth/google/callback. Then save the client ID and the client secret:

bunx wrangler secret put GOOGLE_CLIENT_ID
bunx wrangler secret put GOOGLE_CLIENT_SECRET

allowedEmails in .beep-me/deploy.json becomes ALLOWED_EMAILS: a comma-separated list of Google accounts. Use * to let any account sign up. If the list is empty, only the first account that signs in can use Beep Me.

The Worker applies the database schema on the first request. bunx wrangler d1 migrations apply beep-me --remote also works.

Settings

Name

Kind

Purpose

APP_SECRET

secret

32+ random characters. Encrypts channel keys and signs sessions.

GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET

secret

Google sign-in, and the Gmail channel.

ALLOWED_EMAILS

var, from allowedEmails in .beep-me/deploy.json

The Google accounts that can sign in.

PUBLIC_URL

var, from domain in .beep-me/deploy.json

The custom domain. Other hosts redirect to it. bun run cli domain sets it.

Related MCP server: AgentPing

Connect your agents

Client

How

Claude (web, desktop, mobile)

Open Customize > Connectors. Select + Add, then Add custom connector. Paste https://<your-worker>/mcp. Keep the recommended sign-in options. Sign in. Choose the agent's limits.

Claude Code

Run claude mcp add --transport http --scope user beep-me https://<your-worker>/mcp. Then run /mcp in Claude Code to sign in.

Claude Code, Codex, pi (plugin)

Install the Beep Me plugin from this repository's marketplace. See The plugin.

Other MCP clients

Use the same URL. The client signs in with OAuth at the first connection.

Scripts, cron, CI, headless agents

Create a token under Agents. Use it as a Bearer token on /mcp or /v1/notify.

Each OAuth connection shows an approval page. On this page, you set the agent name, its highest priority, and its channels.

The plugin for Claude Code, Codex, and pi

plugins/beep-me adds hooks to Claude Code, Codex, and pi. Create a token under Agents > Connect > Plugin. The tab shows the commands with your URL and token filled in.

  • In Claude Code, permission prompts, AskUserQuestion questions, and plans go to your phone when nobody answers in the terminal for 15 seconds. The first answer wins: the terminal or your phone.

  • When an agent asks something with notify, the plugin waits for your answer at no token cost. In Claude Code and pi, the answer wakes the agent, also when the session is idle. In Codex, the session continues with your answer when the turn ends.

  • In Codex, approval requests can go to your phone too. Set BEEPME_PROMPTS=on.

claude plugin marketplace add yannelli/beep-me
claude plugin install beep-me@beep-me
echo '{"url":"https://<your-worker>/mcp","token":"beep_..."}' | claude plugin configure beep-me@beep-me --values-stdin

Codex uses codex plugin marketplace add yannelli/beep-me and codex plugin add beep-me@beep-me, with BEEPME_URL and BEEPME_TOKEN in your shell profile. pi uses /claude:plugin install yannelli/beep-me. Each deployment documents the plugin at /docs/agents/plugin.

REST

curl -X POST https://<your-worker>/v1/notify \
  -H "Authorization: Bearer $BEEPME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Nightly backup finished","priority":"low","topic":"backups"}'

# Plain text works too. Put the options in headers.
curl -d "Deploy finished" -H "Authorization: Bearer $BEEPME_TOKEN" \
  -H "X-Priority: medium" -H "X-Topic: api" https://<your-worker>/v1/notify

# Ask a question, then wait up to 30 seconds for the answer.
curl -X POST https://<your-worker>/v1/notify \
  -H "Authorization: Bearer $BEEPME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Ship the redesign?","priority":"high","options":["Ship it","Wait until Monday"]}'
curl "https://<your-worker>/v1/replies?message_id=<id>&wait_seconds=30" \
  -H "Authorization: Bearer $BEEPME_TOKEN"

MCP tools

Tool

What it does

notify

Sends a message. Inputs: message, title, priority (low, medium, high, urgent), topic, topic_thread, channels (the agent picks channels), fallbacks, url, dedupe_key, attachments (up to 10 files), options (2 to 10 choices), expect_reply, sender_name. Returns the message ID, the channels that got the message, the waiting fallback steps, a watch URL for questions, and the routing notes.

notification_status

Shows where a message from this agent went, its SMS delivery receipts, its answer count, and its fallback steps.

get_replies

Returns what you sent back: text replies, choices, reactions, and files. Each answer has from (the channel and how Beep Me matched it) and in_reply_to (the message and every channel it went to). Inputs: message_id, since, wait_seconds (up to 50), include_read, limit. Marks the answers read.

list_channels

Lists the channels the agent can use, with ids, kinds, topic threads, and how you can answer on each.

cancel_fallbacks

Stops the waiting fallback steps of a message. POST /v1/messages/<id>/fallbacks/cancel does the same with a token.

help

Guides with examples: overview, notify, channels, topics, replies, waiting, fallbacks, examples.

Beep Me also serves three skills (beep-me-notify, beep-me-ask-and-wait, beep-me-fallbacks) through the MCP skills extension and as prompts. beep-me-ask-and-wait shows agents how to wait for your answer with a shell loop on the watch URL, so the wait costs no tokens.

Fallbacks send a message again to other channels when nobody answers, a send fails, or a text is not confirmed. Set them for each priority under Routing, or let the agent set them on one message. Beep Me checks them every minute.

The prompt notify-when-done tells the agent to send a message when the current task finishes or gets stuck. The server instructions tell agents when to notify and how to pick a priority.

How Beep Me routes a message

  1. The agent's priority cap lowers the priority if necessary.

  2. Beep Me holds the message if you paused all messages, muted the agent, or muted the topic. A muted topic holds only low and medium messages.

  3. Beep Me merges an identical message from the same agent into the first one if it arrives inside the collapse window (default: 10 minutes). Beep Me edits the first Telegram message to show the count.

  4. If an agent goes over its hourly message cap, Beep Me holds its messages. You get one alert.

  5. The first rule that matches picks the destinations. If no rule matches, the priority route picks them.

  6. During quiet hours, messages below the break-through level skip the text and arrive without sound.

  7. A text over the agent's hourly text cap goes to the next route down.

  8. When no destination is usable, the message goes to the next route down. Beep Me writes every decision to the log.

Until you edit routes, they follow your channels: texts for urgent and high, the Telegram main chat for medium, and topic threads for low.

Docs

Every deployment serves its own docs at /docs, for example https://beep-me.<you>.workers.dev/docs. Readers do not need to sign in. The docs cover setup, each agent client, each channel, routing, and the MCP and REST reference. Code examples show the address of the deployment you read them on.

To add or change a page, read docs/docs-site.md and run bun run check:docs.

Local development

cp .dev.vars.example .dev.vars   # set APP_SECRET to 32+ random characters
bun run dev                       # http://localhost:5173

On localhost, Continue as developer signs you in without Google. On localhost, Beep Me polls getUpdates to link Telegram, because Telegram cannot reach a local webhook.

Command

Does

bun run dev

Runs the Worker and the dashboard with hot reload (Vite and workerd)

bun run build

Builds the Worker and the dashboard into dist/

bun run typecheck

Type-checks the Worker, the dashboard, and the config

bun run check:docs

Checks the docs pages: missing pages, unknown components, and broken links

bun run deploy

Builds and deploys with Wrangler

Project layout

src/shared/     Types and schemas shared by the Worker and the dashboard
src/worker/     The Worker: MCP server, OAuth, routing, channels, JSON API
  channels/     One adapter per provider
  core/         Routing, quiet hours, delivery, replies, the notify pipeline
  hooks/        Incoming replies, choices, and delivery receipts from providers
  integrations/ Guided Telnyx and Resend setup
  auth/         Google sign-in, sessions, the OAuth approval page
src/web/        The dashboard (React 19, Tailwind CSS 4)
  docs/         The docs site at /docs: nav.ts, MDX pages in content/, components
scripts/cli/    The setup and management CLI (bun run cli)
plugins/beep-me/ The plugin for Claude Code, Codex, and pi: hooks and their Node.js scripts
migrations/     D1 schema
docs/           API reference and research notes (start at docs/INDEX.md)

Security

  • Beep Me encrypts channel keys with AES-GCM, with a key derived from APP_SECRET.

  • Beep Me stores agent tokens as SHA-256 hashes and shows each token once.

  • Beep Me uses OAuth 2.1 with PKCE, an approval page for each client, Client ID Metadata Documents, and dynamic client registration.

  • Beep Me checks the agent in D1 on every call, so a revoke takes effect on the next request.

  • The Telegram webhook checks a secret for each channel. SMS receipt URLs and ntfy choice buttons carry an HMAC.

  • Text replies must carry a valid signature: Ed25519 with your Telnyx public key, or X-Twilio-Signature with your Twilio auth token. Resend replies must carry a valid Svix signature. Beep Me records email replies only from the channel's Send to address.

  • If an SMTP server does not offer STARTTLS, Beep Me does not send your password to it.

Status

These items passed local checks:

  • The full OAuth flow, and MCP on the 2025 and 2026-07-28 protocol versions.

  • Token agents, REST, collapse, the rate cap, and revoke.

  • Webhook delivery and the SMTP STARTTLS guard.

These items have no check yet: a real deploy, and live sends through each provider. See docs/INDEX.md for verified provider facts and open items.

For Gmail with Google sign-in, turn on the Gmail API in your Google Cloud project. If your Google app is in Testing status, Google stops the refresh token after 7 days. Publish the app to prevent this.

Contributing

Read CONTRIBUTING.md for setup, the commit format, and how releases work. Releases follow Semantic Versioning; see CHANGELOG.md. Report security problems privately as described in SECURITY.md. This project follows the Code of Conduct.

Maintainer

Built by Ryan Yannelli (@yannelli on GitHub).

License

MIT

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables sending real-time and webhook notifications when AI agents complete tasks, with support for Discord, Slack, Teams, Feishu, Ntfy, and custom webhooks.
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Let your AI agent notify you via email, Slack, Discord, or webhook using a single tool.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents and applications to send notifications through configurable channels such as Telegram or a JSONL file, with queued delivery, status tracking, idempotency, and event-based routing.
      2
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to reach users on their phone through push notifications, and to raise urgent, escalating alarms that fall back to a voice call until someone acknowledges. It also ships hooks that notify users automatically when Claude Code or Codex needs input or finishes a turn.
      3
      9 npm
      MIT