watush-mcp

A robust Telegram MCP server for agents. Any agent — Claude Code, Claude Desktop, or Codex — can use it to message, update, clean up after, and ask questions of you or named people (partner, family, friends) through your own Telegram bot.

So you can say:

"message me on telegram once the build is done" "keep me updated on the GPU temps in one telegram message" "ping the family: dinner at 7" "message me on watush if you need anything while I'm out"

…and it routes to the right person. You (the owner) always get an audit note for anything sent to, edited for, deleted from, or asked of someone else.

It cannot browse your chats: the only thing it ever reads is the reply to a question it is actively waiting on.

How it works

• Five tools are exposed to the agent:

  • send_telegram_message({ text, to? }) — send a message. to is a person's name or a tag (case-insensitive). Omit to (or use "me") to message yourself. A tag shared by several people fans out to all of them. Returns each delivered message's message_id.

  • edit_telegram_message({ message_id, text, to? }) — rewrite a sent message in place. Perfect for live status messages: one message that keeps updating instead of a wall of notifications. No time limit.

  • delete_telegram_message({ message_id, to? }) — remove a sent message to cut noise. Telegram allows this within 48 hours of sending.

  • ask_telegram_question({ question, options?, to?, timeout_seconds? }) — ask a question with tap-to-answer buttons (or free-text replies — you can always just type instead). The agent blocks until you answer; your tap or reply is returned to it directly. The question message updates itself to show what you answered.

  • list_recipients() — lets the agent discover who/what tags it can address (names + tags only; chat IDs are never exposed).

• Markdown formatting works in all message/question text: **bold**, *italic*, `code`, fenced blocks, [links](url), ~~strike~~, headers. Rendered as native Telegram formatting, with an automatic plain-text fallback so a message is never lost to a formatting error.

• Timing is the agent's job. "in 30 minutes" is handled by the agent that calls the tool; the tool itself always sends now.

• No background process. Stdio MCP servers are spawned on demand by each client, so there's nothing to "start on login" — installing simply registers the server with your agents so it's available whenever they run.

Related MCP server: Telegram Agent for Codex

Setup

1. Install (build + wire all agents)

cd ~/Code/watush-mcp
./install.sh

This installs dependencies, compiles the TypeScript, creates config.yaml (if missing), and registers the server with Claude Code, Codex, and Claude Desktop — whichever are present. Existing agent configs are backed up first. Re-run it any time (e.g. after a Node version change).

2. Configure config.yaml

config.yaml holds your secrets and is git-ignored — it is never committed. Copy the example if you don't have one yet:

cp config.example.yaml config.yaml && chmod 600 config.yaml

botToken: "123456789:ABC..."        # from @BotFather
owner:
  name: "Owner"
  chatId: "111111"                  # your numeric Telegram ID (gets audit copies)
recipients:
  - name: "Alice"
    chatId: "222222"
    tags: ["partner", "household"]
  - name: "Bob"
    chatId: "333333"
    tags: ["friend", "team"]
auditToOwner: true

3. Find chat IDs

Everyone you want to message (including you) must DM the bot once. You have two ways to capture their numeric IDs — neither runs in the background:

a) On-demand /chatinfo listener (recommended)

npm run chatinfo

This starts a temporary listener. Each person DMs the bot /chatinfo and the bot replies to them with their own chat ID (it's also printed in your terminal). Press Ctrl-C when you're done — it does not keep running.

npm run chatinfo -- --once         # auto-stop after the first /chatinfo
npm run chatinfo -- --timeout=60   # auto-stop after 60 seconds

b) One-shot snapshot

npm run chats

Prints the chat ID + name of everyone who recently messaged the bot. (Reads only — never writes your config.)

Copy the right IDs into config.yaml.

4. Restart Claude Desktop

If you use Claude Desktop, restart it so it loads the new server. Claude Code and Codex pick it up on their next run.

Usage

Just ask, in any agent:

"message me on telegram: deploy finished ✅" "text my partner: leaving now" "notify the family: flight landed"

Live-updating messages — one message, continuously rewritten:

"track the download and update me in a single telegram message" "keep a running status of the migration on watush"

Cleanup — the agent can delete its own noise:

"delete those progress messages now that it's done"

Questions — the agent asks, you tap (or type), the agent continues:

"message me on watush if you need anything" → later, your phone shows "Deploy to prod now, or wait for the tests?" with [Deploy now] [Wait] buttons. Tap one and the agent carries on with your answer.

Behind the scenes the agent calls send_telegram_message, edit_telegram_message, delete_telegram_message, or ask_telegram_question. Anything involving a person other than you also sends you an audit note like:

🔔 Audit — sent to Alice: leaving now
✏️ Audit — edited message to Alice: updated ETA 18:30
❓ Audit — asked Alice: pizza or sushi?

How questions work (and their limits)

• The question arrives as a normal Telegram message from your bot, with one button per option. Tapping answers instantly; typing a message answers free-form. With several questions pending in one chat, swipe-reply to a specific question message to target it; a plain message answers the newest.

• The asking agent waits as long as its timeout_seconds (default 15 min). In Claude Code, long waits are automatically moved to a background task, so the agent keeps working until your answer arrives.

• Several agent sessions can wait on questions at once — watush coordinates them so only one process polls Telegram (Telegram allows a single poller per bot token), and answers are routed to whichever session asked.

• One machine at a time. The coordination state is per-machine, but the bot token's update stream is global. If agents on two different machines wait on questions at the same moment, one machine's poller can consume (and lose) the other machine's answers, and they compete for the single polling slot. Keep simultaneous questions on one machine, or give each machine its own bot token (each token gets its own state dir automatically).

Configuration reference

Environment overrides (handy for CI / secrets managers): TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID (owner), TELEGRAM_RECIPIENTS (a JSON array of recipients, merged over the file), and WATUSH_CONFIG (alternate config path).

Resolving to

Uninstall

./uninstall.sh           # unregister from all agents (keeps config.yaml)
./uninstall.sh --purge   # also remove dist/ and node_modules/

Security

• config.yaml is git-ignored and chmod 600. The token and chat IDs never leave your machine and are never committed.

• No chat browsing: there is no tool to read message history or list chats. Incoming messages are only read while a question is pending, and only to resolve that question.

• Question state (pending questions, answers, poll coordination) lives in ~/.watush/state/<token-hash>/, keyed by a hash of the bot token; override the location with WATUSH_STATE_DIR.

• If your token ever leaks, rotate it in @BotFather (/revoke) and paste the new one into config.yaml.

Development

npm install
npm run build      # tsc -> dist/
npm test           # offline unit tests (resolution, config, audit logic)
npm start          # run the MCP server over stdio

Project layout:

src/config.ts       load YAML config + resolve recipients (pure, tested)
src/format.ts       Markdown → Telegram HTML + plain-text fallback (pure, tested)
src/telegram.ts     Telegram Bot API client: send/edit/delete/callbacks/updates
src/deliver.ts      resolve + send/edit/delete + audit orchestration (pure, tested)
src/questions.ts    question engine: shared state, poll lock, answer spool
src/mcp-server.ts   the MCP server (five tools)
src/list-chats.ts   read-only "npm run chats" helper
src/listen.ts       on-demand "npm run chatinfo" listener
bin/watush-mcp-server  launcher that resolves node for GUI apps / nvm
scripts/            config editors used by install/uninstall

MIT licensed.