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

How It Works: Data Flow

Before setting things up, it is important to understand what happens with your data:

1. telegram-mcp runs locally on your computer and receives messages directly from Telegram servers
2. Your authorization token (session string) is never sent anywhere - it is stored only on your device
3. When you ask Claude to process messages (summary, search, draft), message text is sent to the Anthropic API for processing - just as if you had copied and pasted it into Claude manually

Claude vs ChatGPT: An Important Distinction

Before setting up, you need to understand the fundamental difference between platforms:

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

If you already have Docker installed, you can use it too, but Python is simpler and lighter. Docker is not required.

Step 1: Getting 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: Generating 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: Registering the MCP Server (~2 min)

MCP (Model Context Protocol) is a "plugin" system for Claude Code. Now we will connect Telegram as a plugin.

If you are using the /telegram-mcp-setup skill in Claude Code, it will create a wrapper script automatically. If setting up manually - in Terminal:

# 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 - close and reopen it so the MCP server loads.

Step 5: Testing 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.

Security: What You Need to Know

Session String Is More Than a Password

A regular password requires 2FA for access. A session string bypasses 2FA - it is an already-authorized token. If it leaks, an attacker can:

• Read all messages in all chats, groups, and channels
• Send messages on your behalf
• Download files, photos, and documents
• Access your contact list
• Do all of this silently, with no notifications

Current Version Limitations

telegram-mcp gives full account access. There is no "read-only" mode and no chat filtering. When Claude reads your messages, it has access to all chats.

Safe Usage Rules

1. Never send automatically - always use draft mode (save_draft), review, and send manually
2. Do not share your session string - it gives full account access
3. Enable 2FA - additional protection for your Telegram account
4. Check active sessions - Telegram → Settings → Privacy → Active Sessions
5. Rotate the session string every 90 days - as a security hygiene practice
6. Try on a test account first - if you have sensitive business chats, test on a secondary account first

Complete Disconnection

To completely disconnect Telegram from Claude Code:

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

"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 @.

"Session expired"

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

"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.