Better Telegram MCP Server

Better Telegram MCP

mcp-name: io.github.n24q02m/better-telegram-mcp

MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot integrations and MTProto (Telethon) for full user-account access.

Features

• Dual mode -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
• 6 mega-tools with action dispatch: messages, chats, media, contacts, config, help
• Auto-detect mode -- Set bot token for bot mode, or API credentials for user mode
• Web-based OTP auth -- Browser-based authentication with remote relay support for headless environments
• Tool annotations -- Each tool declares readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• MCP Resources -- Documentation available as telegram://docs/* resources
• Security hardened -- SSRF protection, path traversal prevention, error sanitization

Quick Start

Claude Code Plugin (Recommended)

claude plugin add n24q02m/better-telegram-mcp

After install, set your bot token: claude config set mcpServers.better-telegram-mcp.env.TELEGRAM_BOT_TOKEN "your-token". Get one from @BotFather. For user mode (MTProto), set TELEGRAM_API_ID + TELEGRAM_API_HASH instead.

MCP Server

Python 3.13 required -- Python 3.14+ is not supported.

Bot Mode Setup

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

User Mode Setup

1. Go to my.telegram.org, login with your phone number
2. Click "API development tools", create an app
3. Note your api_id (integer) and api_hash (32-char hex string)
4. On first run, a local web page opens for OTP authentication

Option 1: uvx

Bot mode:

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

User mode:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-telegram-mcp"],
      "env": {
        "TELEGRAM_API_ID": "12345678",
        "TELEGRAM_API_HASH": "your-api-hash-from-my-telegram-org",
        "TELEGRAM_PHONE": "+1234567890"
      }
    }
  }
}

Option 2: Docker

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

For user mode in Docker, mount the session directory with -v ~/.better-telegram-mcp:/data so the session persists across container restarts.

Tools