convez.ai
MCP ServerIntegração & APIsAvançado
sridharandevcom

Telegram MCP Server (Dual-Mode)

sridharandevcom/telegram-mcp-ts

Controle Telegram via Claude com segurança contra banimento de conta

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP TypeScript-nativo que conecta Claude e outros clientes de IA ao Telegram em modo dual: conta de usuário (MTProto via gramjs) ou bot (Bot API). Oferece 31 ferramentas com proteção contra banimento de conta, rate limiting adaptativo e confirmação antes de enviar.

Instalação

$npx convez-ai sridharandevcom/telegram-mcp-ts

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automatizar leitura e resposta de mensagens Telegram via Claude
  • Integrar Telegram em workflows de AI para atendimento e notificações
  • Gerenciar canais e grupos com assistentes de IA mantendo segurança de conta

Veredito

Implementação robusta e bem-pensada de MCP para Telegram com real preocupação com segurança de conta (rate limiting adaptativo, circuit breaker, respeito a backpressure). Requer Node.js 18+ e credenciais válidas, mas a documentação de setup é clara. Ideal para quem quer automação Telegram em Claude sem riscos de banimento.

README

A tradução para o português deste README ainda está na fila.

telegram-mcp-ts

A TypeScript-native, dual-mode Model Context Protocol server for Telegram.

It lets an MCP client (Claude Desktop, Cursor) read and act on Telegram on your behalf — either as a personal user account (MTProto, via gramjs) or as a bot account (Bot API), depending on which credentials you supply.

Status: 31 tools across MTProto (16) and Bot API (15) modes, with a confirm-before-send safety layer, an account-ban-avoidance engine (adaptive rate limiting + flood/429 backpressure + circuit breaker), and a doctor self-check. Distributed via npx, with full exported types.

🚀 Getting Started — read this first

👉 Click here for the full Step-by-Step Install & Setup Guide

The easiest way to install this and connect it to Claude Desktop / Claude Code / Cursor — getting credentials, configuring your client, and running your first test, all explained for beginners.


Install (quick reference)

Published on npm as telegram-mcp-ts. Your MCP client runs it on demand — no manual install needed:

npx telegram-mcp-ts            # the server (your client launches this for you)
npx telegram-mcp-ts-auth login # one-time login for personal-account (MTProto) mode

Prefer the commands on your PATH? Install globally: npm install -g telegram-mcp-ts.

The rest of this README is the full reference (modes, all tools, safety, advanced flags).

Reliability & account safety

Driving a personal account via automation can get it banned if it looks like spam — the most common failure across Telegram MCP tools. This server is built to avoid that:

  • Safe mode (default on): conservative, jittered rate limits. Loosen with TELEGRAM_SAFE_MODE=false at your own risk.
  • Honors backpressure: respects Telegram FLOOD_WAIT and Bot API 429 retry_after automatically, then adaptively widens its gaps.
  • Confirm-before-send + cold-contact warnings so nothing is sent by accident.
  • Resilience: retry-with-backoff, a circuit breaker, and auto-reconnect.
  • doctor self-check:
    npx telegram-mcp-ts doctor      # or: node dist/index.js doctor
    
    Verifies Node version, credentials, session validity + connectivity, and bot token.

See ACCOUNT-SAFETY.md for the full threat model and what the server does about it. Bulk/mass sending is intentionally not supported.


Requirements

  • Node.js ≥ 18.18 (developed/tested on Node 20). Node 14/16 will not work — the MCP SDK and gramjs require modern Node.
  • MTProto mode: Telegram API ID + API HASH from https://my.telegram.org → API development tools.
  • Bot API mode: a bot token from @BotFather.

You can enable either mode or both. Pick at least one.

⚠️ Use a throwaway Telegram account for write testing. Aggressive send/edit/delete carries a ban risk. The session string grants full access to whatever account you log in with — treat it like a password and never commit it.


Quick start (zero install, via npx)

1. One-time auth (MTProto / user-account mode only)

Skip this if you only want Bot API mode. The login asks for your phone number, the login code Telegram sends, and your 2FA password (if any), then prints a reusable session string (the only thing written to stdout, so you can capture it):

npx telegram-mcp-ts-auth login > session.txt
CommandWhat it does
npx telegram-mcp-ts-auth loginInteractive login; prints a reusable session string.
npx telegram-mcp-ts-auth logoutRevokes the session on Telegram's servers.
npx telegram-mcp-ts-auth clear-sessionExplains how to forget the local session (does not revoke).

2. Add to your MCP client config

Claude Desktop — claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code / Cursor — a .mcp.json in your project root (same mcpServers shape).

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "telegram-mcp-ts"],
      "env": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "your_api_hash_here",
        "TELEGRAM_SESSION": "the_session_string_from_login",
        "TELEGRAM_BOT_TOKEN": "123456:your_bot_token_from_botfather"
      }
    }
  }
}

Include only the env vars for the mode(s) you want — MTProto needs the three TELEGRAM_API_*/SESSION vars; Bot API needs only TELEGRAM_BOT_TOKEN.

Optional flags:

  • TELEGRAM_SAFE_MODE (default true) — conservative rate limits; see ACCOUNT-SAFETY.md.
  • TELEGRAM_META_MODE (default false) — lazy tool loading: expose only list_tools + call_tool instead of the full surface, to save client context. Tools are discovered via list_tools and invoked via call_tool (same validation + confirm-before-send guarantees). Recommended once 30+ tools are enabled.
  • TELEGRAM_TRANSPORT (default stdio) — set to http to serve over Streamable HTTP instead of stdio. Configure with TELEGRAM_HTTP_PORT (default 3000) and TELEGRAM_HTTP_HOST (default 127.0.0.1). The MCP endpoint is the server root /.

All tools carry MCP annotations (readOnlyHint / destructiveHint / openWorldHint) so clients can warn before destructive actions like delete_message.

Restart your client. The telegram server appears with the tools for whichever mode(s) you configured.


Local development (from source)

npm install
npm run build
node dist/auth/cli.js login    # local equivalent of `npx telegram-mcp-ts-auth login`

Then point your client config at the local build instead of npx:

"command": "node",
"args": ["C:\\path\\to\\telegram-mcp\\dist\\index.js"]

Modes

The server detects its mode from the environment:

Env vars presentMode enabledTools
TELEGRAM_API_ID + TELEGRAM_API_HASH (+ TELEGRAM_SESSION)MTProto (user account)the 16 MTProto tools below
TELEGRAM_BOT_TOKENBot APIthe 15 bot tools below

Both can be enabled at once (31 tools); the two modes share no code except the registration interface, so a bug in one cannot affect the other.

Bot API setup

  1. Create a bot with @BotFather → /newbot → copy the token.
  2. Set TELEGRAM_BOT_TOKEN in your config's env block (no login/session needed — the token is the credential).
  3. Restart. The get_bot_info / send_bot_* tools appear automatically.

Tools

ToolModeKindDescription
get_meMTProtoreadAuthenticated account info (id, name, username, phone, premium).
get_dialogsMTProtoreadList chats/groups/channels with IDs, unread counts, last-message preview.
get_messagesMTProtoreadRead message history from a chat (paginated via offsetId).
search_messagesMTProtoreadSearch messages within a chat, or globally if chat is omitted.
send_messageMTProtowriteSend a text message (optional reply). Confirm-guarded (see below).
edit_messageMTProtowriteEdit the text of one of your messages.
delete_messageMTProtowriteDelete one or more messages (destructive; revoke by default).
mark_as_readMTProtowriteMark a chat's messages as read (non-destructive).
download_mediaMTProtoreadDownload a message's media/file to local disk.
get_unread_summaryMTProtoreadCompact, AI-friendly digest of unread messages grouped by chat.
send_scheduledMTProtowriteSchedule a message for future delivery. Confirm-guarded.
get_topic_messagesMTProtoreadRead messages from a forum topic in a supergroup.
reply_to_topicMTProtowritePost into a specific forum topic. Confirm-guarded.
send_mediaMTProtowriteSend a photo/video/audio/file as your account (local path or URL). Confirm-guarded.
join_chatMTProtowriteJoin a public chat by @username or a private one by invite link. Rate-capped.
leave_chatMTProtowriteLeave a channel/supergroup or basic group.
get_bot_infoBot APIreadThe bot's own info (getMe) + capability flags.
send_bot_messageBot APIwriteSend a text message as the bot. Confirm-guarded.
send_documentBot APIwriteSend a file (URL, file_id, or local upload). Confirm-guarded.
send_pollBot APIwriteSend a poll (2-10 options). Confirm-guarded.
send_inline_keyboardBot APIwriteSend a message with tappable inline buttons. Confirm-guarded.
handle_callbackBot APIreadLong-poll for inline-button taps and return the callback data.
send_bot_mediaBot APIwriteSend photo/video/audio/voice/animation as the bot. Confirm-guarded.
send_media_groupBot APIwriteSend an album (2–10 items). Confirm-guarded.
edit_bot_messageBot APIwriteEdit the bot's message text/caption.
delete_bot_messageBot APIwriteDelete messages the bot can delete (destructive).
forward_messageBot APIwriteForward message(s) between chats. Confirm-guarded.
copy_messageBot APIwriteCopy a message (no "forwarded from"). Confirm-guarded.
send_chat_actionBot APIwriteShow a "typing…"/"uploading…" status.
get_fileBot APIreadDownload a file the bot received (by file_id) to disk.
get_chat_infoBot APIreadChat title/type/description + member count.

Confirm-before-send safety pattern

Every message-sending tool (send_message, send_media, send_scheduled, reply_to_topic, and the bot send_* / forward_message / copy_message tools) plus the destructive delete_message, delete_bot_message, and leave_chat are two-step so an agent cannot send, delete, or leave by accident:

  1. First call (omit confirmToken) → validates input, resolves the target, and returns a preview with a single-use confirmToken. Nothing happens.
  2. Second call (same arguments plus confirmToken) → the token is verified against the exact target+content, consumed, and only then is the action performed.

The token is server-minted, unguessable, single-use, expires after 5 minutes, and is bound to the precise content — so there is no single-call path to a send or delete, and a token minted for one action can't be reused for a different one.

Other writes (edit_message, edit_bot_message, mark_as_read) are not gated — they're reversible. join_chat is rate-limited rather than confirm-gated.


Permissions & approvals

There are two independent safety layers — know which is which:

  1. Your MCP client's approval ("allow this tool call?") — the real human-in-the-loop. This is controlled entirely by your client, not by this server. The server can't (and shouldn't) approve itself past it.
  2. This server's confirm gate (preview → confirmToken) — an in-tool guard that stops an accidental single-call send/delete. Always on for sends + destructive actions.

Every tool carries MCP annotations (readOnlyHint, destructiveHint, openWorldHint) so your client can prompt intelligently — auto-allow the safe reads, prompt for the risky writes.

Reducing approval prompts (optional, per client)

  • Claude Desktop / Cursor — approve on first use and pick "always allow" for the tools you trust.
  • Claude Code — add to permissions.allow in .claude/settings.local.json, e.g. "mcp__telegram" (all tools) or specific ones like "mcp__telegram__get_me".

Recommended posture

  • Reads (get_*, search_*, download_media) are safe to auto-allow.
  • Writes — for a hard human gate, keep your client's prompt on for them; otherwise the confirm gate still prevents accidental one-call sends (note: an autonomous agent can satisfy the confirm gate itself by calling twice, so it's an accident-guard, not a human gate — pair it with client approval if you need a true checkpoint).

Usage examples

You invoke tools by asking your MCP client (Claude, Cursor, …) in plain English — it picks the right tool and arguments. The prompts below are representative; adapt the placeholders:

  • <chat> — "me" (Saved Messages), an @username, or a numeric chat id. For numeric ids, run get_dialogs first so the session knows the chat.
  • <id> — a message id (returned by send/read tools). <chat-id> / <user-id> — numeric ids.
  • Sends preview first — you'll get a preview + confirmToken; reply "confirm and send" to actually send.

⚠️ When experimenting with write tools on a personal account, keep them in Saved Messages ("me") and read ACCOUNT-SAFETY.md first.

MTProto — reads (safe)

ToolExample promptResult
get_me"Which Telegram account am I using?"your id, name, username
get_dialogs"List my 20 most recent chats with their IDs."chats with ids, types, unread counts
get_messages"Read the last 10 messages from <chat>." (or "…from <chat> since 2026-06-01.")messages with sender, text, reactions, poll counts
search_messages"Search <chat> for 'invoice'." / "Search all my chats for 'invoice'."matching messages
get_unread_summary"Summarize my unread messages — 5 chats, 3 each."compact digest grouped by chat
get_topic_messages"Read topic <topicId> in <forum-group>."messages from that forum topic
download_media"Download the media from message <id> in <chat>."saved file path + size

MTProto — writes (preview → confirm)

ToolExample promptResult
send_message"Send 'hello' to <chat>." → "confirm and send"preview, then status: sent + message id
send_media"Send the photo at <path-or-url> to <chat>." → confirmmedia posted
send_scheduled"Schedule 'reminder' to <chat> for 2026-06-10T09:00:00Z." → confirmstatus: scheduled
reply_to_topic"Post 'hi' to topic <topicId> in <forum-group>." → confirmposted in the topic
edit_message"Edit message <id> in <chat> to 'updated'."message text changes
mark_as_read"Mark <chat> as read."unread badge clears
join_chat"Join @channelname." (or an invite link)status: joined (rate-limited)
leave_chat"Leave <chat>." → confirmpreview, then status: left
delete_message"Delete message <id> from <chat>." → confirmdestructive — preview, then removed

Bot API (needs TELEGRAM_BOT_TOKEN)

Target a user who has tapped Start on your bot (use their <user-id>) or a group the bot is in.

ToolExample promptResult
get_bot_info"Show the bot's info."bot id, username, flags
get_chat_info"Get chat info for <chat-id>."title, type, member count
get_file"Download bot file with file_id <id>."saved path + size
send_bot_message"Send 'hi from bot' to <user-id>." → confirmmessage sent
send_bot_media"Send the photo <url> as the bot to <user-id>, type photo." → confirminline photo
send_document"Send the file <url> as the bot to <user-id>." → confirmdocument message
send_media_group"Send an album to <user-id>: <url1>, <url2>." → confirm2-item album
send_poll"Send a poll to <user-id>: 'Lunch?' options Pizza, Sushi." → confirma poll
send_inline_keyboard"Send buttons to <user-id>: 'Pick one', A→a and B→b." → confirmmessage with buttons
handle_callback(after sending buttons and tapping) "Listen for button taps for 30 seconds."the tapped callbackData
send_chat_action"Show a typing action in <user-id>.""typing…" appears briefly
forward_message"Forward message <id> from <src> to <user-id>." → confirmforwarded (with header)
copy_message"Copy message <id> from <src> to <user-id>." → confirmcopied (no header)
edit_bot_message"Edit bot message <id> in <user-id> to 'new text'."bot's message changes
delete_bot_message"Delete bot message <id> in <user-id>." → confirmpreview, then removed

Development

npm run typecheck   # tsc --noEmit (strict)
npm run build       # tsup -> dist/
npm run dev         # tsup --watch

Project layout

src/
  index.ts          # registers enabled tools, starts the stdio server
  client/           # gramjs (MTProto) client wrapper
  tools/            # one file per tool + the registration interface
  lib/              # config/mode detection, zod-based errors, rate limiter
  auth/             # login / logout / clear-session CLI

Engineering rules

  1. Every tool input is validated with zod before any Telegram call.
  2. No raw errors reach the client — failures return structured, human-readable text.
  3. Reads are safe; writes (and destructive actions) are guarded by a confirm-before-send preview.
  4. One tool per file, registered through a single interface.
  5. Per-chat and per-user rate limiting to stay clear of spam detection.
  6. MTProto and Bot API modes are isolated.

License

MIT

Ver o original no GitHub

Bom para

Relacionados