Telegram (tg-mcp)

io.github.qelphyboxPublished by GitHub account qelphyboxv0.1.3Updated Nov 14, 2026

Your personal Telegram account for AI: read, search and sum up chats. QR login, no API key.

VerifiedStreamable HTTPWeb executableKnowledge & MemoryCommunication & Collaboration

Overview

AI-generated overview

Unofficial remote MCP server that gives AI clients read access to your personal Telegram account, plus optional, user-confirmed drafts, sends, reactions and…

What you can do
  • Read chats and messages: list chats and folders, read messages with media metadata, topics and reply threads, get chat and member info, find chats by name
  • Search messages with Telegram's own word search, across chats or within one, narrowed by date, media, sender or topic
  • Fetch media: view photos and thumbnails as images, transcribe voice messages and video notes, or get a short-lived download link
  • Manage drafts: list existing drafts and write text into a chat's message field for you to send yourself
  • Write to chosen chats: send messages (confirmed by you unless you opted out), set or remove reactions, mark chats or topics as read
  • Run guided prompts for catching up on unread chats and…
When to use it
Useful when you want an assistant to summarize what you missed in Telegram, search your own chat history for facts or links, or draft and send replies without leaving the AI client. Best for people who keep real conversations in Telegram and want read-only access first.
Requirements
A remote streamable-HTTP endpoint (public instance at connector.tgmcp.dev) added to an MCP client that supports OAuth. Login is by scanning a QR code in Telegram under Settings, Devices, Link Desktop Device, plus the account's cloud password if two-step verification is on. No API key or environment variables for the hosted instance; self-hosting needs HTTPS, a Telegram app's api_id and api_hash, and a database path.
Before you install
It acts on your real Telegram account: with the send scope it can message chats on your allow-list, react and mark chats read without confirmation, and drafts appear on all your devices. Grant only the scopes you need; leaving drafts and sends unticked keeps it read-only. The cloud password is entered on the server's own login page. Removing the server in the AI client alone may not log it out; end the session in Telegram's Devices settings. It is unofficial and not affiliated with Telegram.

Installation

In SourceWeft

  1. Open Telegram (tg-mcp) in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.qelphybox%2Ftg-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "telegram-tg": {
      "type": "http",
      "url": "https://connector.tgmcp.dev/mcp"
    }
  }
}

README

tg-mcp

Unofficial remote MCP server that gives AI clients (Claude, ChatGPT, Gemini, Claude Code, Cursor, …) read access to your personal Telegram account and, only if you allow it, lets them write Drafts that you send yourself, or send messages to chats you choose, each confirmed by you, and react and mark as read there. You add a URL, log in by scanning a QR code, and you're done.

Not affiliated with or endorsed by Telegram. It uses the Telegram API through its own registered app ("Unofficial MCP Server"). Nothing is ever edited or deleted, and nothing is forwarded. A connection writes only what you ticked for it: Write Drafts, text in a chat's message field that you send yourself; Send messages, messages to the chats you chose, each one confirmed by you in your browser unless you ticked "without asking me", plus reactions and read marks in those chats (never confirmed). Without either, nothing is ever written.

Quick start

Website: tgmcp.dev. Public instance: https://connector.tgmcp.dev/mcp

Claude Code

sh
claude mcp add --transport http telegram https://connector.tgmcp.dev/mcp

Then run /mcp in Claude Code → telegram → Authenticate. A browser opens:

  1. Scan the QR code with Telegram on your phone: Settings → Devices → Link Desktop Device.
  2. If your account has a cloud password (two-step verification), type it on the same page. It goes only to this server's login page, never through the AI client or the chat.
  3. Allow on the consent screen. Reading is always included; leave Write Drafts and Send messages unticked to keep the connection read-only. Write Drafts ticked, the AI can also put text into a chat's message field on all your devices (save_draft), replacing the Draft there; only you can send it. Send messages ticked, you choose the chats it may send to (Chat folders, your 100 most recent chats, or a chat found by name: only chats you already have), and whether it may send there without asking you each time (off unless you tick it). Then each message the AI sends (send_message) waits for you on this server's confirmation page, opened in this same browser: Claude Code opens it for you, other clients hand you the link. In those chats it may also react to messages (react) and mark them as read (mark_read) without asking.

Claude (web/desktop/mobile, free plan too): Settings → Connectors → Add custom connector → the same URL. ChatGPT (paid plans): Settings → Apps & Connectors → Advanced → turn on Developer mode, then Create → the same URL. Gemini (personal Google accounts, add it on the web): Settings → Connected apps → Add a custom app → the same URL. Other MCP clients: add it as a streamable-HTTP server; they discover OAuth on their own.

Tools

ToolWhat it returns
whoamiThe connected account: id, name, @username, and its Chat folders (chat_folders: id, title, emoji, rules when a folder is defined by rules rather than a list of chats), in the app's order.
list_chatsChats, most recent first: id, title, type, unread count, muted and marked_unread flags, last-message preview (text or caption, and the kind of media). Paged by cursor; archived lists the Archive folder. unread_only lists only chats with unread messages or marked as unread ("what did I miss"): Telegram can't filter by unread, so one call reads at most 500 chats and says unread_scan_truncated when it stopped there; next_cursor reads on. chat_folder lists one Chat folder as its tab in the app (folder-pinned first, archived chats included; with unread_only too); folders defined by rules aren't supported yet.
get_messagesMessages of one chat, newest first: sender, date, text (or caption), media (kind: photo, video, video note, voice, audio, document, sticker, GIF, location, contact, poll or other; with duration, size, MIME type, file name and dimensions when Telegram sends them), reply/forward/edit marks, reactions (count per emoji, custom emoji summed as custom, Stars as paid), a t.me link to the message (channels and supergroups) and pinned; in a forum, each message's topic and the page's topics (id → title of the Topics it mentions), and topic reads one Topic only. Paged by before_id; pinned_only reads only the pinned messages; since/until narrow by time; around_id gives a window around one message (e.g. a search hit), continued with before_id / after_id; thread_of gives the chain of messages one message replies to, up to its root or depth ancestors (default 10, max 50), saying where a deleted parent broke it (broken_at) or which chat it goes on in (continues_in).
get_chat_infoTitle, type, @username of one chat; a group's or channel's description and member count. For a user, the profile Telegram shows the account: bio, last-seen status (online, last_seen with the exact time, or recently / last_week / last_month / long_ago when hidden), bot flag and bot description, verified/premium/scam/fake flags, phone and birthday only when shown to the account, and the number of common groups and channels; common_chats: true also lists them (at most 20, ids usable with the other tools). A forum lists its topics (up to 50: id, title, closed, pinned; topics_truncated when there are more).
get_membersMembers of a group, supergroup or channel: id (usable with the other tools), name, @username, role (creator / admin / member), bot flag. query filters by name or @username, admins_only lists only the creator and admins; Telegram's approximate total count. Paged by cursor, up to 200 per page (the last page may be empty). The list may be incomplete: Telegram hides members in some groups (members_hidden), shows a channel's subscribers only to its admins (an error says so) and stops listing a large group after about 10,000 members.
search_messagesTelegram's own search by words (not meaning), newest first: across all chats, or in one with chat_id. Each hit: its chat (id, title, type), message id, date, sender, a ~300-character snippet around the match, the kind of media, and the reactions, link, pin and forum topic of get_messages (titles in the page's topics); read it in context with get_messages around_id. Narrow with since/until and media; across chats with chat_type and archived, in one chat with from (a sender, or me) and, in a forum, topic. Paged by cursor, at most 50 hits per page, no total count.
get_mediaThe media of one message (chat_id, message_id, mode). Mode view: the picture itself as image content the model looks at, so a client without a shell (Claude on the web, desktop or phone) sees it: a photo in Telegram's ~800 px size (size: "large": ~1280 px), the thumbnail of a video, video note, GIF, sticker or file, or a whole album (up to 4 images in message order, album_truncated when there are more), at most ~1 MB per call, as Telegram's own JPEGs (no processing on the server), with a short text saying what each image is. Mode transcribe: what is said in a voice message or video note, as text, by Telegram's own transcription (the audio never leaves Telegram; no other speech-to-text is used): it waits up to 20 s and answers done with the text (up to 16000 characters) or pending with retry_after_s; it needs Telegram Premium or Telegram's weekly free trial (trial_remaining says what is left), otherwise it is an error pointing to download. Mode download: a Media link for an agent with a shell to fetch with curl or wget (url, expires_at, mime_type, size_bytes, duration_s, suggested_filename). It works for 5 minutes and 3 downloads, without a token, for photos (original size), videos, video notes, voice messages, audio, documents, stickers and GIFs up to 20 MB. The file is streamed from Telegram straight into the download, never stored. Voice messages are OGG/Opus and video notes MP4: convert or transcribe them locally (or use transcribe).
find_chatsThe account's own chats and contacts by name, title or @username (@ optional), via Telegram's chat search: id, title, type, @username, at most 30. Contacts without a chat are included; public chats the account hasn't joined never are. No paging and no fallback: a chat it doesn't find is still in list_chats.
get_draftsThe account's Drafts (unsent text in chats' message fields, typed in any Telegram app or written by save_draft), newest first: chat (id, title, type, Saved Messages marked is_self), forum topic, reply_to, date and text without its formatting. At most 100 Drafts and ~40,000 characters per call, newest kept (truncated when older ones are left out).
save_draftWrites; needs the draft Scope (absent from tools/list without it). Puts text into one chat's message field on all your devices, replacing the Draft there; "" clears it. Nothing is sent: you send it from Telegram. format markdown (default: **bold**, *italic* / _italic_, `code`, ``` code blocks, [text](https://…) links; anything else stays as typed) or plain. At most 4096 characters once formatted, never split. reply_to a message of the same chat; in a forum, topic (or a reply_to in a Topic) says which Topic's field. Any chat of the account's, Saved Messages too; each call counts against the writes budget. Returns saved / cleared, never the text.
send_messageSends as you; needs the send Scope (absent from tools/list without it). Sends text to one chat of the connection's Send allow-list (any other chat is an error). Unless you allowed "without asking me", you confirm it first on the confirmation page (below): clients with URL elicitation (Claude Code) open it and the call waits for your decision, others get pending_confirmation with the confirm_url to give you. Text as save_draft's (Markdown subset or plain, 1 to 4096 characters once formatted, never split; reply_to; topic or a reply_to in a Topic in a forum), no media, no forwarding. Returns sent (message_id, date), cancelled, expired, drafted or pending_confirmation. The same text to the same chat within 60 s of sending it is refused as "already sent: message N". Each message counts against the writes budget and the chat's Send cap (5 a minute); a refusal says when to retry, and nothing is retried or queued.
reactWrites; needs the send Scope. Sets your reaction on one message of a chat of the Send allow-list to one standard emoji (as Telegram lists them: 👍 ❤ 🔥 …; ❤️ and ❤ are the same), replacing your previous reaction there; emoji: null removes it. Custom emoji and paid (Stars) reactions are refused, and so is an emoji the chat doesn't allow (some chats allow only some reactions, or none). Never confirmed; setting the same reaction again is no error. Counts against the writes budget, not the Send cap. Returns set (with the emoji as Telegram names it) or removed.
mark_readWrites; needs the send Scope. Marks a chat of the Send allow-list as read on all your devices, up to its latest message or up to up_to; in a forum, topic marks only that Topic. In a private chat the other person sees their messages as read. Never confirmed; marking again is no error. Counts against the writes budget, not the Send cap. Returns the chat, topic and up_to it marked.

Experimental, off by default: with TG_MCP_EXPERIMENTAL_DOCUMENTS=1, get_media also takes mode document (a PDF or plain-text file as an embedded resource in the result; a #58 prototype that may change or go away).

Chat ids look like user:123~a-MGLzhi9Ek, chat:456 (basic group) or channel:789~18YMXnDF6JI (channels and supergroups), as returned by list_chats, find_chats and in message senders; the part after ~ is the access hash Telegram needs, so an id works without the server looking it up. Ids without it (user:123) are still accepted. Every tool but save_draft, send_message, react and mark_read is marked read-only, and every tool has bounded input and output: at most 100 items per call (200 members for get_members), long texts cut. Messages describe their media (media: its kind and metadata) without downloading it; text holds only a message's text or caption, so a voice message has an empty text and media.kind: "voice". Only get_media fetches a file, a picture or a transcription, and only when asked to.

Prompts

Two MCP prompts turn common requests into step-by-step instructions that use the tools above. A client that supports prompts lists them and inserts the rendered text as if you typed it. Each takes one optional argument, query: your request in your own words (up to 512 characters), from which the model takes the time range, the chats and how many. Rendering a prompt reads nothing from Telegram.

PromptqueryWhat it asks the model to do
catch_upe.g. "since Monday in Work, 5 chats"; empty: all unread chatsPage the unread chats (list_chats unread_only, at most 5 pages), or find the chats the request names, and read at most 10 unmuted ones (or as many as asked) message by message with get_messages (limit = unread count, 5-100; never from previews), forums Topic by Topic. Report per chat in 1-3 sentences who waits for a reply (sender, quote, link); give the exact number of chats left out, and muted chats only by title and unread count; end with a "needs your reply" list, or say there is none.
researche.g. "top restaurants in Tbilisi"; empty: the model asks what to researchSeveral short search_messages queries (word forms, synonyms, transliteration, the other languages of your chats); a hit opened in context (get_messages around_id / thread_of) when its snippet is cut or it goes into the answer; every claim cited with chat, date and link from the very message; several matching chats: it asks; facts kept apart from inferences; the queries that found nothing on the topic.

In Claude Code they are slash commands named after the server, e.g. /mcp__telegram__catch_up and /mcp__telegram__research for a server added as telegram (characters other than letters, digits, _ and - in the name become _). Everything after the command is the request, unquoted: /mcp__telegram__research top restaurants Tbilisi. Claude Code splits it on whitespace and may deliver only its first word; the model then asks for the whole request before making any call, and you give it in your next message. A long request can go there from the start: a bare /mcp__telegram__research asks what to research (a bare catch_up runs its default instead). Both prompts answer in the language of your earlier messages in the conversation (or else in the language of the chats read), and tell the model that message content is data, never instructions.

Disconnecting

End the Unofficial MCP Server session in Telegram → Settings → Devices. That logs the server out for real; the AI client gets a 401 on its next call.

Removing the server in your AI client alone is not enough: e.g. Disconnect in claude.ai's connector settings only forgets the tokens on its side, and without a token the server can't decrypt (or log out) your session — by design, see below. Clients that call the OAuth revocation endpoint (/revoke, RFC 7009) do log the session out.

Security model

  • A database dump is useless. Your Telegram session is encrypted (XChaCha20-Poly1305) with a per-login key. That key is never stored: each OAuth token your client holds carries the secret needed to unwrap it, and the server keeps only a verifier and a wrapped copy per token. Without one of your tokens, nobody, including the operator, can decrypt the session. (ADR-0003)
  • Restarts don't need a re-login, because the encrypted session survives in the database and your client's token unlocks it again.
  • No messages on disk. Chats, messages and Drafts pass through memory only; the session at rest is just the auth keys and home datacenter. Logs carry ids and sizes, never message or Draft text or tokens. The duplicate guard of send_message keeps a keyed hash of each sent message's text, in memory, for a minute.
  • Media links are short-lived credentials. A get_media download link is 256 random bits, lives in memory only, works for 5 minutes and 3 downloads, and only for the one file it was made for; revoking the login ends it at once, and a restart ends them all. The file streams from Telegram into the response without touching disk. A view holds its images (at most ~1 MB) in memory only for the one call.
  • Scopes. A connection gets only what you tick on the consent screen: read always, draft if you allow it (save_draft: Drafts only you can send), send if you allow it and choose the chats it may send to (send_message, each message confirmed by you unless you chose otherwise; react and mark_read in the same chats, never confirmed; organize is not offered yet). Tools outside a connection's Scopes are neither listed nor callable, the server's instructions to the AI name only what its tools can do, and changing Scopes means connecting again. (ADR-0005)
  • The Send allow-list is sealed like the session. The chats a send connection may write to (send, react, mark as read), and whether it may send without asking, are encrypted with the same per-login key, so a database dump shows neither which chats nor (beyond a rough size) how many. Only chats you already have can be chosen; folders are read into their chats when you allow; changing the list means connecting again. Choosing the chats asks Telegram a few times for your own account, before the AI gets any token: that page needs the login's cookie, and is rate-limited per IP and per login. Logs carry how many chats, never which.
  • Sends are confirmed in your own browser. Unless you ticked "without asking me", every message waits up to 10 minutes on this server's confirmation page, which shows the chat, the exact text (links with where they lead) and who asks. Only the browser where you gave Consent can press Send or Cancel: allowing send sets a cookie there (HttpOnly, SameSite=Strict, only sent to /confirm) whose verifier is sealed with the chat list, so the AI, which may see the page's link, can't send with it; any other browser can only make the message a Draft. Clients with URL elicitation (Claude Code) open the page for you; others hand you the link. Waiting messages live in memory only; a confirmed one still counts against the writes budget and the chat's Send cap. (ADR-0005)
  • Your password never reaches the AI. QR login and the cloud password happen on this server's own pages.
  • OAuth 2.1 with PKCE (S256), dynamic client registration, single-use authorization codes, rotating refresh tokens bound to their client, and a consent screen that leads with where the login is sent, names the account, and shows the self-declared client name as unverified.
  • Telegram limits are respected. Requests per account are rate-limited, and Telegram's FLOOD_WAIT blocks that account's calls of the same kind (reading, search, file downloads, transcription or writes) until it passes instead of being retried around. Writes (Drafts, sent messages, reactions and read marks) also have their own budget, 20 per account in any 10 minutes by default: a write over it, or during a FLOOD_WAIT of writes, fails at once saying when to retry, and is never retried or queued; so does a message over a chat's Send cap (5 a minute by default) or into a group's slow mode. Telegram's PEER_FLOOD (the account is limited for spam) is reported as such, never retried.
  • Anonymous callers can't make it flood Telegram. The OAuth endpoints are rate-limited per client IP, and only a few logins (each one a Telegram connection) can be in progress at once, server-wide and per IP.

Self-hosting

You need a server with HTTPS on a public hostname (OAuth requires it) and your own Telegram app:

  1. Register an app at my.telegram.org/apps → note api_id and api_hash. Please keep "Unofficial" in its title.
  2. Run the image behind a TLS-terminating reverse proxy that forwards the Host header:
sh
docker run -d --name tg-mcp --restart unless-stopped \  -p 127.0.0.1:8080:8080 \  -v tg-mcp-data:/data \  -e TG_MCP_PUBLIC_URL=https://tg.example.com \  -e TG_MCP_DB_PATH=/data/tg-mcp.db \  -e TG_MCP_API_ID=123456 \  -e TG_MCP_API_HASH=your_api_hash \  ghcr.io/qelphybox/tg-mcp:latest

If the proxy sets or appends X-Forwarded-For from the address it accepted the connection from (Caddy and kamal-proxy do; nginx with proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for), also pass -e TG_MCP_TRUST_FORWARDED_FOR=1, so the per-IP rate limits of the OAuth endpoints see real client addresses instead of the proxy's.

Images are published for linux/amd64 and linux/arm64 on every release tag. All settings are environment variables, documented in .env.example.

This repository also deploys itself with Kamal to a single VPS (zero-downtime rollouts, automatic Let's Encrypt): see docs/deploy.md. scripts/setup-deploy.sh walks through the one-time setup, including server hardening.

Development

sh
cargo test                                   # unit + HTTP-level tests, no network neededTG_MCP_FAKE_TELEGRAM=1 cargo run             # local server with a fake Telegram accountcargo test -- --ignored live_                # MTProto handshake against real Telegram DCs

Rust, tokio, axum, rmcp, grammers, SQLite. Domain vocabulary is in GLOSSARY.md, decisions in docs/adr/, contributor and agent conventions in CLAUDE.md.

License

MIT, see LICENSE.

Source: README.md at commit f70eaab

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v0.1.3LatestNov 14, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts