better-telegram-mcp 1.0.5

Production-grade MCP server for Telegram — dual-mode Bot API + MTProto, mega-tool pattern

better-telegram-mcp

Production-grade MCP server for Telegram with dual-mode support: Bot API (via httpx) for quick bot integrations and MTProto (via Telethon) for full user-account access including message search, history browsing, contact management, and group creation.

Features

• 6 mega-tools with action dispatch: messages, chats, media, contacts, config, help
• Dual mode: Bot API (httpx) for bots, MTProto (Telethon) for user accounts
• 3-tier token optimization: Only 6 tools registered instead of 30+ individual endpoints
• Tool annotations: Each tool declares readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• MCP Resources: Documentation available as telegram://docs/* resources
• Auto-detect mode: Set bot token for bot mode, or API credentials for user mode

Quick Start

Bot Mode

1. Open Telegram, search for @BotFather
2. Send /newbot, follow prompts to name your bot
3. Copy the token (format: 123456789:ABCdefGHI-JKLmnoPQRstUVwxyz)
4. Run:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF uvx --python 3.13 better-telegram-mcp

User Mode

1. Go to https://my.telegram.org
2. Login with your phone number (OTP sent via Telegram, not SMS)
3. Click "API development tools"
4. Create an app, note api_id (integer) and api_hash (32-char hex)
5. Authenticate once, then run:

export TELEGRAM_API_ID=12345
export TELEGRAM_API_HASH=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

# Step 1: Authenticate (interactive, one-time)
uvx --python 3.13 better-telegram-mcp auth

# Step 2: Run the server
uvx --python 3.13 better-telegram-mcp

Auth CLI

The auth command creates a Telethon session file for user mode. This must be done once before using user mode.

# Basic auth (prompts for phone + OTP)
TELEGRAM_API_ID=... TELEGRAM_API_HASH=... uvx --python 3.13 better-telegram-mcp auth

# With phone number pre-set (only prompts for OTP)
TELEGRAM_API_ID=... TELEGRAM_API_HASH=... TELEGRAM_PHONE=[phone] \
  uvx --python 3.13 better-telegram-mcp auth

# With 2FA password pre-set
TELEGRAM_API_ID=... TELEGRAM_API_HASH=... TELEGRAM_PASSWORD=my2fapass \
  uvx --python 3.13 better-telegram-mcp auth

# Named session (for multiple accounts)
TELEGRAM_API_ID=... TELEGRAM_API_HASH=... \
  uvx --python 3.13 better-telegram-mcp auth --session-name work

Session file: Stored at ~/.better-telegram-mcp/<name>.session with 600 permissions (owner-only). Treat this file like a password.

2FA handling: If your account has Two-Step Verification enabled, set TELEGRAM_PASSWORD env var or enter it interactively when prompted.

Configuration

All configuration is via environment variables with TELEGRAM_ prefix:

Variable	Required	Default	Description
TELEGRAM_BOT_TOKEN	Bot mode	-	Bot token from @BotFather
TELEGRAM_API_ID	User mode	-	API ID from my.telegram.org
TELEGRAM_API_HASH	User mode	-	API hash from my.telegram.org
TELEGRAM_PHONE	No	Interactive prompt	Phone number for auth (e.g., [phone])
TELEGRAM_PASSWORD	No	Interactive prompt	2FA password (if enabled)
TELEGRAM_SESSION_NAME	No	default	Session file name (for multiple accounts)
TELEGRAM_DATA_DIR	No	~/.better-telegram-mcp	Data directory for session files

Mode detection: If TELEGRAM_API_ID + TELEGRAM_API_HASH are set, user mode is used (priority). Otherwise, TELEGRAM_BOT_TOKEN is used for bot mode. No silent fallback between modes.

MCP Config Examples

Claude Code

# Bot mode
claude mcp add telegram -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF -- uvx --python 3.13 better-telegram-mcp

# User mode (after running auth)
claude mcp add telegram -e TELEGRAM_API_ID=12345 -e TELEGRAM_API_HASH=abc123 -- uvx --python 3.13 better-telegram-mcp

Claude Desktop / Cursor

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456:ABC-DEF"
      }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "telegram": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-telegram-mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456:ABC-DEF"
      }
    }
  }
}

Docker

# Bot mode
docker run -i --rm -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp

# User mode (auth must be done on host first, then mount session)
docker run -i --rm \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=abcdef123456 \
  -v ~/.better-telegram-mcp:/data \
  n24q02m/better-telegram-mcp

Docker config for MCP clients:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_BOT_TOKEN",
        "n24q02m/better-telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456:ABC-DEF"
      }
    }
  }
}

Note: For user mode in Docker, authenticate on the host first (uvx better-telegram-mcp auth), then mount the session directory with -v ~/.better-telegram-mcp:/data.

Mode Capabilities

Feature	Bot Mode	User Mode
Send messages	Y	Y
Edit messages	Y	Y
Delete messages	Y	Y
Forward messages	Y	Y
Pin messages	Y	Y
React to messages	Y	Y
Search messages	-	Y
Browse history	-	Y
List chats	-	Y
Get chat info	Y	Y
Create groups/channels	-	Y
Join/Leave chats	Partial	Y
Manage members	Y	Y
Admin promotion	Y	Y
Chat settings	Y	Y
Forum topics	Partial	Y
Send media (photo/file/voice/video)	Y	Y
Download media	-	Y
List contacts	-	Y
Search contacts	-	Y
Add contacts	-	Y
Block/Unblock users	-	Y

Tool Reference

Use the help tool for full documentation:

help(topic="messages")  # Message operations
help(topic="chats")     # Chat management
help(topic="media")     # Media send/download
help(topic="contacts")  # Contact management
help(topic="all")       # Everything

Troubleshooting

Error	Cause	Fix
No Telegram credentials found	Neither bot token nor API credentials set	Set TELEGRAM_BOT_TOKEN or TELEGRAM_API_ID + TELEGRAM_API_HASH
Invalid bot token	Token revoked or wrong	Regenerate via /token in @BotFather
Session not authorized	Session file missing or expired	Run uvx better-telegram-mcp auth
PhoneNumberInvalidError	Wrong phone format	Include country code with + (e.g., [phone])
SessionPasswordNeededError	2FA enabled	Set TELEGRAM_PASSWORD env or enter interactively
FloodWaitError	Too many auth attempts	Wait the indicated seconds
requires user mode	Action not available in bot mode	Switch to user mode (API ID + Hash)
Session lost after Docker restart	Data volume not mounted	Add -v ~/.better-telegram-mcp:/data

Compatible With

Also by n24q02m

Server	Description	Install
better-notion-mcp	Notion API for AI agents	npx -y @n24q02m/better-notion-mcp@latest
better-email-mcp	Email (IMAP/SMTP) for AI agents	npx -y @n24q02m/better-email-mcp@latest
wet-mcp	Web search, extraction, library docs	uvx --python 3.13 wet-mcp@latest
mnemo-mcp	Persistent AI memory	uvx mnemo-mcp@latest
better-godot-mcp	Godot Engine for AI agents	npx -y @n24q02m/better-godot-mcp@latest

Contributing

See CONTRIBUTING.md.

License

MIT - See LICENSE.