Better Telegram MCP

Better Telegram MCP

Production-grade MCP server for Telegram with dual-mode Bot API and MTProto. 6 composite tools covering messages, chats, media, contacts management with 3-tier token optimization.

Category
访问服务器

README

better-telegram-mcp

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

CI codecov PyPI Docker License: MIT Python Telegram MCP semantic-release Renovate

<a href="https://glama.ai/mcp/servers/n24q02m/better-telegram-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/n24q02m/better-telegram-mcp/badge" alt="better-telegram-mcp MCP server" /> </a>

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, 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. Add to your MCP config with all required env vars (see examples below)
  5. Start using — on first run, auth happens automatically:
    • Server auto-sends an OTP code to your Telegram app (not SMS, not browser)
    • A terminal window opens for you to enter the OTP code directly (no AI relay needed)
    • If 2FA is enabled: set TELEGRAM_PASSWORD env var, or enter it in the terminal prompt
    • In headless environments (Docker, SSH, no desktop): use config(action='auth', code='12345') as fallback
  6. Done — session file persists at ~/.better-telegram-mcp/<name>.session, no more auth needed on subsequent runs

Security: The session file has 600 permissions (owner-only). Treat it like a password — anyone with this file can access your Telegram account.

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 User mode - Phone number with country code (e.g., +84912345678). Required for auto OTP send on startup.
TELEGRAM_PASSWORD No - Two-Step Verification password. If set, used automatically during sign-in. If not set and 2FA is enabled, sign-in will fail with SessionPasswordNeededError.
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 (auto-auth on first run)
claude mcp add telegram -e TELEGRAM_API_ID=12345 -e TELEGRAM_API_HASH=abc123 -e TELEGRAM_PHONE=+84912345678 -- uvx --python 3.13 better-telegram-mcp

Claude Desktop / Cursor

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",
        "TELEGRAM_PASSWORD": "your-2fa-password-if-enabled"
      }
    }
  }
}

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 (auto-auth on first run, mount session dir for persistence)
docker run -i --rm \
  -e TELEGRAM_API_ID=12345 \
  -e TELEGRAM_API_HASH=abcdef123456 \
  -e TELEGRAM_PHONE=+84912345678 \
  -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, mount the session directory with -v ~/.better-telegram-mcp:/data so the session persists across container restarts. On first run, complete auth via config(action='auth', code='YOUR_CODE') (terminal auth is not available in Docker).

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
Authentication required Session not yet authorized Complete auth in the terminal window, or use config(action='auth', code='YOUR_CODE') in headless environments
PhoneNumberInvalidError Wrong phone format Include country code with + (e.g., +84912345678)
SessionPasswordNeededError 2FA enabled but no password Set TELEGRAM_PASSWORD env var in your MCP config
FloodWaitError Too many auth attempts Wait the indicated seconds before retrying
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
OTP sent but where? Code goes to Telegram app Check the Telegram app on your phone (not SMS, not browser). Look for a message from "Telegram" with a login code.
How to enter OTP code? Terminal window should open Enter the code in the terminal window that opens automatically. If no terminal (headless/Docker), use config(action='auth', code='12345')
Need to re-send OTP Code expired or not received Call config(action='send_code') to request a new code

Compatible With

Claude Desktop Claude Code Cursor VS Code Copilot Antigravity Gemini CLI OpenAI Codex OpenCode

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 with hybrid search 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.

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选