Better Telegram MCP

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)

Via marketplace (includes skills: /setup-bot, /channel-post):

/plugin marketplace add n24q02m/claude-plugins
/plugin install better-telegram-mcp@claude-plugins

Or install this plugin only:

/plugin marketplace add n24q02m/better-telegram-mcp
/plugin install better-telegram-mcp

Set credentials in ~/.claude/settings.local.json or shell profile. See Environment Variables.

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

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-telegram-mcp"]
    }
  }
}

// Cursor (~/.cursor/mcp.json), Windsurf, Cline, Amp, OpenCode
{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": ["--python", "3.13", "better-telegram-mcp"]
    }
  }
}

# Codex (~/.codex/config.toml)
[mcp_servers.telegram]
command = "uvx"
args = ["--python", "3.13", "better-telegram-mcp"]

Option 2: Docker

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

Configure credentials in ~/.claude/settings.local.json or your shell profile. See Environment Variables below.

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

Tools

Mode Capabilities

MCP Resources

Configuration

Mode detection: If TELEGRAM_API_ID + TELEGRAM_API_HASH are set, user mode is used. Otherwise, TELEGRAM_BOT_TOKEN is used. No silent fallback -- if neither is set, the server exits with an error.

Auth Flow (User Mode Only)

1. On first run, a web-based auth UI opens in your browser (or URL is logged for headless)
2. Click "Send OTP Code" -- code is sent to the Telegram app (not SMS)
3. Enter the OTP code; if 2FA is enabled, enter your password
4. Session file is saved at ~/.better-telegram-mcp/<name>.session (600 permissions)
5. Tools become active immediately -- no restart needed

Headless auth (Docker/SSH) -- use curl against the auth URL shown in logs:

curl -X POST http://127.0.0.1:PORT/send-code
curl -X POST http://127.0.0.1:PORT/verify -d '{"code":"12345"}'
curl -X POST http://127.0.0.1:PORT/verify -d '{"password":"your-2fa-password"}'  # if 2FA

Security

• SSRF Protection -- All URLs validated against internal/private IP ranges, DNS rebinding blocked
• Path Traversal Prevention -- File paths validated, sensitive directories blocked
• Session File Security -- 600 permissions, 2FA via web UI only (never stored in env vars)
• Error Sanitization -- Credentials never leaked in error messages

Build from Source

git clone https://github.com/n24q02m/better-telegram-mcp.git
cd better-telegram-mcp
uv sync
uv run better-telegram-mcp

Compatible With

Also by n24q02m

Contributing

See CONTRIBUTING.md.

License

MIT -- See LICENSE.