Telegram AI Setup

Why Connect Telegram to AI?

If you have dozens of chats in Telegram, you know the feeling: you open the app and there are 100+ unread messages. Some are important, some can be skipped, but there is no time to sort through them all.

An AI assistant connected to Telegram solves this problem:

• Morning digest - a brief summary of all unread messages: what is urgent, what can wait
• Chat search - find "that conversation about project X" without manual scrolling
• Discussion analysis - summarize long threads, highlight key decisions
• Draft responses - AI prepares a reply, you review and send

In 2026, there are two distinct ways to connect Claude Code to Telegram. They work differently, give you different capabilities, and suit different use cases. This guide covers both.

Two Methods: Channels vs MCP

Before diving into setup, here is how the two approaches compare:

Method 1: Claude Code Channels (Quick Start)

Channels is a built-in feature in Claude Code that connects it to messaging platforms - Telegram, Slack, Discord - as a bot. No third-party tools or API credentials needed. You create a Telegram bot, give Claude the token, and it starts responding to messages.

Step 1: Create a Telegram Bot (~1 min)

1. Open Telegram and search for @BotFather
2. Send /newbot
3. Choose a name for your bot (e.g., "My Claude Assistant")
4. Choose a username (must end in bot, e.g., my_claude_assistant_bot)
5. BotFather will give you a bot token - a string like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Copy it.

Step 2: Connect the Bot to Claude Code (~1 min)

In your terminal, run:

claude channels setup telegram

Claude Code will ask for the bot token you got from BotFather. Paste it in and confirm. That is it - the bot is live.

Step 3: Start Using It

You can now interact with Claude through Telegram in two ways:

• DM the bot - send any message directly to your bot for a private conversation
• Add the bot to a group - mention it with @your_bot_username to get Claude's response in group chats

Channels Limitations

Because Channels works through a Telegram bot, it has the same limitations as any Telegram bot:

• No message history - the bot can only see messages sent after it joined, and only those directed at it
• No unread digests - it cannot read your personal unread messages across chats
• No search - it cannot search through your chat history
• Bot label - messages are clearly marked as coming from a bot

Method 2: MCP Server (Full Access)

The MCP (Model Context Protocol) approach gives Claude full access to your Telegram account - all chats, all history, all contacts. It runs locally on your machine, and your authorization token never leaves your device.

What You Will Need

1. Claude Code - CLI tool from Anthropic (claude.ai/code)
2. Python 3 - usually pre-installed on Mac. Check with python3 --version in Terminal
3. Telegram account - with access to my.telegram.org

Step 1: Get Telegram API Keys (~5 min)

Telegram requires application registration for API access - like a building pass. It is free and takes a couple of minutes.

1. Go to my.telegram.org
2. Enter your phone number (with country code: +1...)
3. Enter the confirmation code (it will arrive in Telegram on all your devices)
4. Navigate to "API development tools"
5. If you do not have an app yet - create one:
   • App title: anything (e.g., "Claude Integration")
   • Short name: unique, Latin letters, 5-32 characters (e.g., "john_claude"). If the name is taken - add numbers.
   • Platform: Desktop
6. Note down api_id (a number) and api_hash (a 32-character string)

Verification: You should have two values - a numeric API ID and a 32-character API Hash.

Step 2: Generate the Session String (~3-5 min)

A session string is an encrypted token of your Telegram session. It allows the application to act on your behalf without re-entering a code on every launch.

Open Terminal (on Mac: Cmd+Space, type "Terminal", Enter) and run:

Option A: Python (Easiest)

# Install the Telegram library
pip3 install telethon

# Run the generator (you will need to enter your data)
python3 -c "
from telethon.sync import TelegramClient
from telethon.sessions import StringSession

api_id = int(input('Enter API ID: '))
api_hash = input('Enter API Hash: ')

with TelegramClient(StringSession(), api_id, api_hash) as client:
    print('\n=== YOUR SESSION STRING ===')
    print(client.session.save())
    print('=== END SESSION STRING ===')
"

Option B: Docker (If Installed)

docker run -it --rm bayramannakov/telegram-mcp:latest python setup_wizard.py

The program will ask for:

1. API ID - the number from step 1
2. API Hash - the string from step 1
3. Phone number - with country code (+1...)
4. Confirmation code - it will arrive in Telegram (check all devices)
5. 2FA password - if enabled

Verification: The result is a string of 300-400 characters (letters, numbers, +, /, =). If the string is shorter than 100 characters - something went wrong. Copy it carefully, without extra spaces.

Step 3: Secure Key Storage (~1 min)

On macOS, we use Keychain - Apple's built-in secure storage. The security command is its Terminal interface.

# Save API ID (-U flag updates if entry already exists)
security add-generic-password -a "api_id" -s "telegram-mcp" -w "YOUR_API_ID" -U

# Save API Hash
security add-generic-password -a "api_hash" -s "telegram-mcp" -w "YOUR_API_HASH" -U

# Save Session String (single quotes - for special characters)
security add-generic-password -a "session_string" -s "telegram-mcp" -w 'YOUR_SESSION_STRING' -U

Verification:

security find-generic-password -a "api_id" -s "telegram-mcp" -w

It should output your API ID. If you see an error - repeat the save command.

Step 4: Register the MCP Server (~2 min)

Now we will connect Telegram as a plugin to Claude Code. If you are using the /telegram-mcp-setup skill in Claude Code, it will create a wrapper script automatically. If setting up manually:

# Register the MCP server
claude mcp add telegram-mcp -s user -- ~/.local/bin/telegram-mcp-docker

# Verify the server was added
claude mcp list

You should see telegram-mcp in the list of servers. Restart Claude Code so the MCP server loads.

Step 5: Test the Connection (~1 min)

Open Claude Code and ask:

Show my recent Telegram chats

If everything is set up correctly, you will see a list of your chats.

Which Method Should You Choose?

Here is a quick decision guide based on what you actually want to do:

• "I want Claude in my team chat" → Channels
• "I want morning message digests" → MCP
• "I want to search old conversations" → MCP
• "I need maximum privacy" → MCP (token stays local)
• "I want the simplest setup possible" → Channels
• "I want AI to draft replies as me" → MCP
• "I want to use Claude on Desktop and mobile" → Channels

The methods are not mutually exclusive. You can use Channels for team chat and MCP for personal message management at the same time.

Security Comparison

Safe Usage Rules (Both Methods)

1. Never let AI send messages automatically - always review before sending, or use draft mode (save_draft) with MCP
2. Do not share your tokens - bot tokens or session strings give access to your account
3. Enable 2FA - additional protection for your Telegram account
4. Check active sessions regularly - Telegram → Settings → Privacy → Active Sessions
5. Rotate credentials - regenerate session strings every 90 days for MCP; regenerate bot tokens via @BotFather if compromised
6. Test on a secondary account first - if you have sensitive business chats, try the setup on a test account

Complete Disconnection

Channels:

1. Remove the bot from your chats
2. Revoke the bot token via @BotFather (/revoke)
3. Remove the channel: claude channels remove telegram

MCP Server:

1. Terminate the session in Telegram: Settings → Privacy → Active Sessions → "Terminate all other sessions"
2. Delete keys from Keychain (three security delete-generic-password commands)
3. Remove the MCP server: claude mcp remove telegram-mcp
4. Delete the wrapper script: rm ~/.local/bin/telegram-mcp-docker

Troubleshooting

Channels: Bot Does Not Respond in Group

By default, Telegram bots can only read messages when @mentioned in groups. Make sure you are tagging the bot (@your_bot_username). Alternatively, disable "Group Privacy" mode via @BotFather to let the bot see all messages.

Channels: "Unauthorized" Error

The bot token is invalid or was revoked. Get a new token from @BotFather and run claude channels setup telegram again.

MCP: "Could not find the input entity"

Incorrect chat ID format. For supergroups, add -100 at the beginning of the ID. For channels, use the username without @.

MCP: "Session expired"

The session string has expired. Regenerate it using the same script from Step 2 and update it in Keychain.

MCP: "Docker daemon not running"

Docker Desktop is not running. Open Docker Desktop and wait 1-2 minutes. If you are not using Docker - this error is not yours; check that the MCP is registered with the correct script.

MCP Server Does Not Appear in Claude Code

Remove and re-add: claude mcp remove telegram-mcp, then repeat the registration. Restart Claude Code.

This article is part of a series of materials for advanced AI users. In our courses, you will learn to effectively use AI tools for building products and automating routine tasks.