Telegram MCP Bridge

An MCP server that lets Claude Code send messages and ask questions via Telegram.

When Claude Code needs your input during a coding task, it sends a Telegram message (with optional inline buttons) and waits for your reply.

Claude Code → MCP tool call → this server → Telegram Bot API → your phone
           ← tool result    ← server      ← you tap a button / type a reply

Tools

Tool	Description
ask_user	Send a question with optional buttons, wait for response (10-min timeout)
notify_user	Fire-and-forget notification

Setup

1. Create a Telegram Bot

1. Open Telegram, message @BotFather
2. Send /newbot, follow prompts — save the bot token
3. Message your new bot (send anything), then visit:

   https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
   

4. Find your chat ID in the response JSON (result[0].message.chat.id)

2. Clone & Install

git clone https://github.com/yourusername/telegram-claude-mcp.git
cd telegram-claude-mcp
npm install

3. Configure Claude Code

Add to ~/.claude/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-claude-mcp/telegram-bridge.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

4. Restart Claude Code

The MCP server starts automatically when Claude Code launches. You should see telegram in your MCP server list.

Usage

Claude Code will automatically have access to ask_user and notify_user tools. You can prompt it to use them:

"If you need to ask me something, use the ask_user Telegram tool"

Or Claude may use them when configured in your project's CLAUDE.md.

License

MIT