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=+84912345678 \
  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:

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

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

Compatible With

Also by n24q02m

Contributing

See CONTRIBUTING.md.

License

MIT - See LICENSE.