Claude Code Telegram Official Plugin: Complete Setup Guide 2026

🎯 Key Takeaways (TL;DR)

• The official Anthropic Telegram plugin for Claude Code lets you chat with your AI assistant directly through Telegram
• Setup requires just 6 steps: create a bot → install plugin → configure token → relaunch → pair → lock down
• The plugin exposes three MCP tools: reply, react, and edit_message for full message control
• Access control defaults to "pairing" mode — switch to allowlist once configured to prevent strangers from accessing your assistant
• No message history or search — the bot only sees messages as they arrive

Table of Contents

1. What is the Claude Code Telegram Plugin?
2. Prerequisites
3. Quick Setup: 6 Steps to Get Running
4. Access Control Deep Dive
5. MCP Tools Reference
6. Working with Photos
7. Important Limitations
8. Comparison: Telegram vs Discord Plugin
9. FAQ
10. Summary & Next Steps

What is the Claude Code Telegram Plugin?

The Claude Code Telegram plugin is an official MCP (Model Context Protocol) server developed by Anthropic that connects a Telegram bot to your Claude Code session. Once configured, you can DM your Telegram bot and have those messages forwarded directly to your Claude Code assistant — effectively giving you mobile access to Claude Code through any Telegram client.

The MCP server logs into Telegram as a bot and provides three tools to Claude: the ability to reply to messages, react with emoji, and edit previously sent messages. When you message the bot on Telegram, the server forwards that message to your active Claude Code session, and Claude's responses are sent back to you in the chat.

This is the official plugin from Anthropic's claude-plugins-official GitHub repository — the same organization that builds Claude itself. It's the recommended way to integrate Telegram with Claude Code, as opposed to third-party solutions.

Prerequisites

Before starting, ensure you have:

💡 Pro Tip
Unlike some MCP servers that support multiple runtimes, the official Telegram plugin specifically requires Bun. If you try to run it with Node.js or Deno, you may encounter unexpected errors.

Quick Setup: 6 Steps to Get Running

Step 1: Create a Bot with BotFather

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

1. Name — the display name shown in chat headers (can contain spaces, e.g., "Milo's Assistant")
2. Username — a unique handle ending in bot (e.g., my_claude_code_bot). This becomes your bot's link: t.me/my_claude_code_bot

BotFather replies with a token that looks like 123456789:AAHfiqksKZ8... — copy the entire token including the leading number and colon.

⚠️ Security Note
Treat this token like a password. Anyone with it can control your bot. Never share it publicly.

Step 2: Install the Plugin

These are Claude Code commands — run claude to start a session first, then execute:

/plugin install telegram@claude-plugins-official /reload-plugins

Check that /telegram:configure tab-completes. If not, restart your session with exit and run claude again.

Step 3: Give the Server the Token

/telegram:configure 123456789:AAHfiqksKZ8...

This writes TELEGRAM_BOT_TOKEN=... to ~/.claude/channels/telegram/.env. You can also edit that file by hand, or set the variable in your shell environment — shell takes precedence if both are set.

Step 4: Relaunch with the Channel Flag

The server won't connect without the channel flag. Exit your session and start a new one with:

claude --channels plugin:telegram@claude-plugins-official

Step 5: Pair

1. DM your bot on Telegram — it replies with a 6-character pairing code
2. In your Claude Code session, enter:

/telegram:access pair <code>

Your next DM reaches the assistant.

✅ Good to Know
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.

Step 6: Lock It Down

Pairing is for capturing IDs. Once you're in, switch to allowlist mode so strangers can't get pairing-code replies. Ask Claude to do it, or run directly:

/telegram:access policy allowlist

Access Control Deep Dive

The plugin supports multiple access policies. See ACCESS.md in the repository 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 (👍 👎 ❤ 🔥 👀 etc.)

MCP Tools Reference

The plugin exposes three tools to the assistant:

Inbound Messages:
Inbound messages trigger a typing indicator automatically — Telegram shows "botname is typing…" while the assistant works on a response.

Working with Photos

When you send photos to the bot:

• Inbound photos are downloaded to ~/.claude/channels/telegram/inbox/
• The local path is included in the <channel> notification so the assistant can Read it
• Telegram compresses photos — if you need the original file, send it as a document instead (long-press → Send as File)

Important Limitations

No History or Search

Telegram's Bot API exposes neither message history nor search. The bot only sees messages as they arrive — no fetch_messages tool exists. If the assistant needs earlier context, it will ask you to paste or summarize.

This also means there's no download_attachment tool for historical messages — photos are downloaded eagerly on arrival since there's no way to fetch them later.

No Thread Fetching

Unlike Discord, Telegram bots can't proactively fetch messages. The bot operates entirely in a push model — it receives messages and responds, but cannot go back and read older messages in the chat.

Comparison: Telegram vs Discord Plugin

The Telegram plugin is generally easier for single-user setups since there's no server invite step — you just DM the bot directly.

FAQ

Q: Can I use the plugin with multiple users?

Yes, but you'll need to configure multi-user access via the access.json policy system. The default pairing policy allows new users to pair themselves, while allowlist mode requires pre-approval.

Q: Why can't I search old messages?

Telegram's Bot API doesn't provide access to message history. The bot only receives messages that arrive while it's running. Plan accordingly by summarizing important conversations.

Q: Can I use this with a group chat?

Yes, see ACCESS.md for groups, mention detection, and group-specific configuration. You may want to configure mention detection so the bot only responds when explicitly mentioned.

Q: Why are my photos blurry?

Telegram compresses photos sent as images. If you need the original quality, send the photo as a document (long-press → Send as File) instead.

Q: What happens if the bot goes offline?

Messages sent while the bot is offline are lost — there's no message queuing. You'll need to resend any messages that weren't responded to.

Summary & Next Steps

The official Claude Code Telegram plugin is the recommended way to bring your AI assistant to Telegram. With just six steps, you get:

• Direct messaging access to Claude Code from any Telegram client
• Three powerful MCP tools for reply, react, and edit
• Flexible access control policies
• Automatic typing indicators
• Photo handling with local download

Next Steps:

1. Create your bot at @BotFather
2. Install with /plugin install telegram@claude-plugins-official
3. Configure your token and relaunch with the channel flag
4. Pair your Telegram account
5. Switch to allowlist policy for security

For advanced configuration (groups, mention detection, skill commands), refer to the full ACCESS.md in the official repository.

Source: Official Anthropic Claude Code Telegram Plugin README