telegram

Telegram

繁體中文

Connect a Telegram bot to your Claude Code with an MCP server.

The MCP server logs into Telegram as a bot and provides tools to Claude to reply, react, or edit messages. When you message the bot, the server forwards the message to your Claude Code session.

Prerequisites

• Bun — the MCP server runs on Bun. Install with curl -fsSL https://bun.sh/install | bash.

Quick Setup

Default pairing flow for a single-user DM bot. See ACCESS.md for groups and multi-user setups.

1. Create a bot with BotFather.

Open a chat with @BotFather on Telegram and send /newbot. BotFather asks for two things:

• Name — the display name shown in chat headers (anything, can contain spaces)
• Username — a unique handle ending in bot (e.g. my_assistant_bot). This becomes your bot's link: t.me/my_assistant_bot.

BotFather replies with a token that looks like 123456789:AAHfiqksKZ8... — that's the whole token, copy it including the leading number and colon.

2. Clone and install the channel.

git clone https://github.com/s1hon/claude-telegram.git
cd claude-telegram && bun install

Register the MCP server (project-level):

claude mcp add telegram -- bun run --cwd /path/to/claude-telegram --shell=bun --silent start

Or register globally so it's available across all projects:

claude mcp add -s user telegram -- bun run --cwd /path/to/claude-telegram --shell=bun --silent start

Then launch with the development channel flag:

claude --dangerously-load-development-channels server:telegram

This flag is required because locally-registered MCP servers are not official plugins. The server: prefix tells Claude Code to load the MCP server you registered with claude mcp add.

3. Give the server the token.

/telegram:configure 123456789:AAHfiqksKZ8...

Writes TELEGRAM_BOT_TOKEN=... to ~/.claude/channels/telegram/.env. You can also write that file by hand, or set the variable in your shell environment — shell takes precedence.

To run multiple bots on one machine (different tokens, separate allowlists), point TELEGRAM_STATE_DIR at a different directory per instance.

For short-lived sessions (cron jobs, one-shot scripts) that need to send messages but shouldn't steal the bot token from a long-running poller, set TELEGRAM_SEND_ONLY=1. The server exposes MCP send tools (reply, send_*, edit_message, etc.) but skips polling and PID ownership — the existing poller keeps receiving inbound messages.

4. Relaunch with the channel flag.

The server won't connect without this — exit your session and start a new one with the appropriate flag from step 2 (either --channels or --dangerously-load-development-channels).

5. Pair.

With Claude Code running from the previous step, DM your bot on Telegram — it replies with a 6-character pairing code. If the bot doesn't respond, make sure your session is running with --channels. In your Claude Code session:

/telegram:access pair <code>

Your next DM reaches the assistant.

Unlike Discord, there's no server invite step — Telegram bots accept DMs immediately. Pairing handles the user-ID lookup so you never touch numeric IDs.

6. Lock it down.

Pairing is for capturing IDs. Once you're in, switch to allowlist so strangers don't get pairing-code replies. Ask Claude to do it, or /telegram:access policy allowlist directly.

Access control

See ACCESS.md for DM policies, groups, mention detection, delivery config, skill commands, and the access.json schema.

Quick reference: IDs are numeric user IDs (get yours from @userinfobot). Default policy is pairing. ackReaction only accepts Telegram's fixed emoji whitelist.

Tools exposed to the assistant

Core messaging

Tool	Purpose
reply	Send text/files to a chat. Supports reply_to (threading), message_thread_id (forum topics), files (attachments), format (text/markdownv2), and inline_keyboard (rows of URL or callback buttons). Auto-chunks long text.
react	Add an emoji reaction. Only Telegram's fixed whitelist (👍 👎 ❤ 🔥 👀 etc).
edit_message	Edit a previously sent text message. Supports inline_keyboard to update buttons, or pass [] to remove them.
delete_message	Delete a message. Bot can delete its own, or any message in groups where it's admin.
forward_message	Forward a message to another chat (shows "Forwarded from" header).
copy_message	Copy a message to another chat without the forwarded header.
pin_message / unpin_message	Pin or unpin a message.

Media sending

Tool	Purpose
send_animation	Send a GIF or H.264 animation.
send_voice	Send a voice message (.ogg OPUS).
send_video	Send a video file.

Special messages