Provides comprehensive access to Telegram via both the Bot API and MTProto (user accounts). Enables managing messages, chats, media, and contacts, including capabilities like searching message history, managing group memberships, and interacting with the Telegram network as either a bot or a full user account.
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,helpDual 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,openWorldHintMCP Resources: Documentation available as
telegram://docs/*resourcesAuto-detect mode: Set bot token for bot mode, or API credentials for user mode
Quick Start
Bot Mode
Get a bot token from @BotFather, then:
TELEGRAM_BOT_TOKEN=123456:ABC-DEF uvx --python 3.13 better-telegram-mcpUser Mode
Get API credentials from my.telegram.org, then:
export TELEGRAM_API_ID=12345
export TELEGRAM_API_HASH=abcdef123456
# Authenticate once (interactive)
uvx --python 3.13 better-telegram-mcp auth
# Run the server
uvx --python 3.13 better-telegram-mcpConfiguration
All configuration is via environment variables with TELEGRAM_ prefix:
Variable | Required | Description |
| Bot mode | Bot token from @BotFather |
| User mode | API ID from my.telegram.org |
| User mode | API hash from my.telegram.org |
| User mode (auth) | Phone number for authentication |
| No | 2FA password (if enabled) |
| No | Session file name (default: |
| No | Data directory (default: |
MCP Config Examples
Claude Code
claude mcp add telegram -- env TELEGRAM_BOT_TOKEN=123456:ABC-DEF uvx --python 3.13 better-telegram-mcpClaude Desktop
{
"mcpServers": {
"telegram": {
"command": "uvx",
"args": ["--python", "3.13", "better-telegram-mcp"],
"env": {
"TELEGRAM_BOT_TOKEN": "123456:ABC-DEF"
}
}
}
}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 -e TELEGRAM_BOT_TOKEN=123456:ABC-DEF n24q02m/better-telegram-mcp
# User mode (mount session data)
docker run -e TELEGRAM_API_ID=12345 -e TELEGRAM_API_HASH=abcdef123456 \
-v ~/.better-telegram-mcp:/data \
n24q02m/better-telegram-mcpDocker config for Claude Desktop:
{
"mcpServers": {
"telegram": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "TELEGRAM_BOT_TOKEN=123456:ABC-DEF",
"n24q02m/better-telegram-mcp"
]
}
}
}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 | Y | 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") # EverythingCompatible With
Any MCP-compatible client
License
MIT