Better Telegram MCP Server

<details> <summary><strong>Sister projects from n24q02m</strong> (click to expand)</summary>

Remote serverstreamable-httpPython

What is the Better Telegram MCP MCP server?

The short version

  • Dual mode — -- Bot API (httpx) for bots, MTProto (Telethon) for user accounts
  • 7 tools — with action dispatch: message, chat, media, contact, config, help, config__open_relay
  • Auto-detect mode — -- Set bot token for bot mode, or API credentials for user mode
  • Web-based OTP auth — -- HTTP-mode browser relay form handles phone, OTP, and 2FA for user accounts (no session strings, no CLI sign-in)
  • Tool annotations — -- Each tool declares readOnlyHint, destructiveHint, idempotentHint, openWorldHint
  • MCP Resources — -- Documentation available as telegram://docs/* resources

The tools it exposes

The server publishes 7 tools. What each one is for:

  • message — send, edit, delete, forward, pin, react, search, history
  • chat — list, info, create, join, leave, members, admin, settings, topics
  • media — send_photo, send_file, send_voice, send_video, download
  • contact — list, search, add, block
  • config — status, set, cache_clear, setup_status, setup_start, setup_reset, setup_complete
  • help — --
  • config__open_relay — --

What it needs from you

Configuration is passed through the environment: TELEGRAM_BOT_TOKEN, PUBLIC_URL, MCP_DCR_SERVER_SECRET, DCR_SERVER_SECRET, TELEGRAM_API_ID, YOUR_ACCOUNT_ID, ACCOUNT_ID, YOUR_PUBLIC_URL. Treat anything key-shaped as a real credential — scope it to the minimum the server needs, and rotate it if it ever lands in a shared config.

Getting it running

Because this one is hosted, setup is mostly authentication — you point your client at the endpoint and approve access. Nothing runs on your machine, so there is no runtime to keep patched.

How it compares

This sits in the team communication group, where several servers overlap in what they claim to do but differ sharply once you actually set them up. Better Telegram MCP's toolset — message, chat, media and 4 more — is a fair guide to whether it matches your workflow. It is maintained by n24q02m; worth a glance at recent repository activity before you build anything load-bearing on it.

We check each listing at SyncDev against the project's documentation before it goes live — if something here drifts out of date, it is a bug worth reporting.

Things to watch

  • Your data travels to the provider's service, so the usual questions apply about what you send and what they retain.
  • Missing credentials fail quietly in some clients — if no tools show up, check the environment block first.
  • Keep per-call confirmation enabled while you learn its behaviour; it is the cheapest safeguard you have.

Available tools

ToolWhat it does
messagesend, edit, delete, forward, pin, react, search, history
chatlist, info, create, join, leave, members, admin, settings, topics
mediasend_photo, send_file, send_voice, send_video, download
contactlist, search, add, block
configstatus, set, cache_clear, setup_status, setup_start, setup_reset, setup_complete
help--
config__open_relay--

How to install the Better Telegram MCP MCP server

{
  "mcpServers": {
    "better-telegram": {
      "command": "uvx",
      "args": ["invocation"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-value",
        "PUBLIC_URL": "your-value",
        "MCP_DCR_SERVER_SECRET": "your-value",
        "DCR_SERVER_SECRET": "your-value",
        "TELEGRAM_API_ID": "your-value",
        "YOUR_ACCOUNT_ID": "your-value",
        "ACCOUNT_ID": "your-value",
        "YOUR_PUBLIC_URL": "your-value"
      }
    }
  }
}

Add to claude_desktop_config.json, then restart Claude Desktop.

Configuration

VariableDescriptionRequired
TELEGRAM_BOT_TOKENCredential the server authenticates with.Yes
PUBLIC_URLEndpoint or connection string the server talks to.Yes
MCP_DCR_SERVER_SECRETCredential the server authenticates with.Yes
DCR_SERVER_SECRETCredential the server authenticates with.Yes
TELEGRAM_API_IDConfiguration value read at startup.Optional
YOUR_ACCOUNT_IDConfiguration value read at startup.Optional
ACCOUNT_IDConfiguration value read at startup.Optional
YOUR_PUBLIC_URLEndpoint or connection string the server talks to.Yes

Example prompts to try

  • Use Better Telegram MCP to message.
  • Use Better Telegram MCP to chat.
  • Use Better Telegram MCP to media.

Frequently asked questions

It connects Better Telegram MCP to MCP-compatible AI assistants such as Claude and Cursor, exposing 7 tools (message, chat, media, and more) that the assistant can call on your behalf. Instead of copying data back and forth by hand, the assistant works with Better Telegram MCP directly.