tdl-mcp
Read-only access to your own Telegram account — list chats, read recent messages, and download media via the local tdl CLI (never sends, edits, or deletes anything).
Check session status (
tg_status) — report whether the local tdl session is logged in and usable; never errors, returns a hint if not logged in.List chats (
tg_chats) — enumerate dialogs as{id, type, name, username}, with an optional case-insensitive substringfilteron name/username/id.Read messages (
tg_messages) — export recent media messages from a chat as compact{id, date, file, text}objects; control the range withlast_n(default 50, max 500) orsince_idfor incremental reads, and toggle text withwith_text.Download media from a chat (
tg_download) — pull files from a chat to a local directory, optionally filtered byextensions(e.g."xlsx,pdf"),last_n(default 100), orsince_id; returns absolute paths and skips already-downloaded files (--skip-same).Download media by link (
tg_download_url) — fetch the media of specifichttps://t.me/...message links (validated), optionally filtered byextensions, into a chosen destination.No api_id/api_hash or in-server login — authentication is done once by you via
tdl login -T qr; the server only runs the tdl binary locally.
Provides read-only access to a personal Telegram account, enabling listing chats, reading recent messages, and downloading media files, without sending or modifying any data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tdl-mcp Show the last 10 messages from @technews"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tdl-mcp
Read-only Telegram access for Claude and other MCP hosts, powered by the
tdl CLI.
List your chats, read recent messages, and download media — from your own Telegram account — with five simple tools. It never sends messages, never modifies anything, and never touches your login.
🇰🇷 한국어 문서는 여기 있습니다 → README.ko.md
Why tdl-mcp?
Most Telegram MCP servers embed an MTProto library (Telethon, gramjs, …),
ask you to create your own Telegram application at my.telegram.org to get an
api_id/api_hash, and many of them can send messages on your behalf.
tdl-mcp takes a different, deliberately boring approach:
Read-only by design. The server can list chats, export messages and download files. That's all. There is no code path that sends, edits, deletes, or logs in.
No
api_id/api_hashsetup. Login is handled once, by you, in your terminal withtdl login -T qr— scan a QR code with your phone and you're done. No Telegram app registration needed.Built on a battle-tested downloader.
tdl(7.5k+ ⭐) does the heavy lifting: fast parallel downloads, resume,--skip-samededuplication.Tiny and auditable. One plain-JavaScript file, two dependencies (
@modelcontextprotocol/sdk,zod), no build step. You can read the whole server in five minutes.
Claude / MCP host ←stdio→ tdl-mcp (Node) →subprocess→ tdl CLI →MTProto→ TelegramRelated MCP server: mcp-telegram
Quick start
1. Install tdl
# macOS
brew install telegram-downloader
# Linux / WSL
curl -sSL https://docs.iyear.me/tdl/install.sh | sudo bash
# Windows (PowerShell)
iwr -useb https://docs.iyear.me/tdl/install.ps1 | iexAny version from the one pinned in .tdl-version upward
should work — CI continuously tests against that pin (see
Compatibility).
2. Log in to Telegram (once)
tdl login -T qrScan the QR code with the Telegram mobile app
(Settings → Devices → Link Desktop Device). The session is stored in
~/.tdl on your machine and shared by every MCP host — you log in exactly
once. tdl-mcp itself never performs or refreshes logins.
3. Add the server to your MCP host
You need Node.js ≥ 22.
Claude Code:
claude mcp add --scope user telegram -- npx -y tdl-mcpClaude Desktop / any other MCP host (generic mcpServers JSON):
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "tdl-mcp"]
}
}
}4. Try it
Ask your assistant things like:
"What Telegram chats do I have? Find the one about quant trading."
"Show me the last 20 messages in @some_channel."
"Download every PDF posted in that channel since message 1500 to ~/Papers."
If a tool reports that you are not logged in, run tdl login -T qr in a
terminal and retry — that's the only manual step there is.
Tools
Tool | Arguments | What it does |
| — | Checks whether the tdl session is logged in. Never errors: returns |
|
| Lists dialogs as |
|
| Exports recent media messages from a chat as compact |
|
| Downloads media from a chat with |
|
| Downloads the media of specific messages by link. Validates every url starts with |
chat accepts either a numeric id or an @username/domain, exactly as shown
by tg_chats.
Environment variables
Variable | Effect |
| Path to the tdl binary. Default: |
| tdl namespace, passed as |
Set them in your host's server config, e.g.:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "tdl-mcp"],
"env": { "TDL_NS": "work" }
}
}
}Compatibility & staying up to date
tdl-mcp shells out to the tdl CLI, so its real dependency is tdl's
command-line surface. That surface is guarded automatically:
.tdl-versionpins the tdl release this package is tested against.scripts/contract.mjsverifies — without logging in — that every flag the server uses (chat ls -o json,chat export -c/-T/-i/-o/--with-content,dl -f/-u/-i/-d/--skip-same, global-n) still exists in that tdl binary. CI runs it on every push and PR.A scheduled workflow watches tdl releases. When a new version appears it runs the contract test against the new binary and scans the release notes for breaking-change markers. Routine updates become a simple version-bump PR; anything suspicious is escalated to an AI-assisted upgrade PR that adapts the wrapper code.
So if you're on a newer tdl than the pin, chances are excellent everything just works — and if it ever wouldn't, this repo finds out before you do.
Development
git clone https://github.com/rixile9999/tdl-mcp.git
cd tdl-mcp
npm install
npm test # smoke (MCP protocol, login-free) + contract (tdl CLI surface)npm run smokespawns the server over stdio and checks the tool catalog,tg_statusshape, and input validation — passes whether or not you are logged in.npm run contractchecks the installed tdl binary against the CLI surface the server uses.scripts/install-tdl.sh [vX.Y.Z]installs a specific (checksum-verified) tdl release if you want to test against another version.
PRs welcome. Please keep the server read-only — tools that send, edit or delete are out of scope for this project.
Security notes
The tdl session in
~/.tdlis a full user-account credential — anyone who can read it can act as your Telegram account. Protect it like an SSH key: don't copy it into repos, shared backups, or other machines.tdl-mcpnever reads or transmits the session itself; it only runs thetdlbinary locally. Nothing leaves your machine except tdl's own Telegram traffic.Downloads go to a directory you choose (
dest), defaulting to~/Downloads/telegram.
Telegram terms-of-service note
tdl drives a regular user session (MTProto), not a bot. Quiet, read-only,
personal-use automation of your own account is generally tolerated, but
aggressive crawling can get an account limited: keep ranges modest
(last_n, since_id), avoid large parallel pulls, and let --skip-same do
its job instead of re-downloading.
License
MIT for everything in this repository.
tdl itself is a separate project licensed under
AGPL-3.0. tdl-mcp does
not bundle, link, or modify tdl — it invokes the binary you installed as a
separate process, so the AGPL applies to tdl, not to this wrapper. You install
tdl yourself through official channels (step 1 above).
Available Tools
5 toolstg_chatsList Telegram chatsA
List the Telegram dialogs (chats/channels/groups/users) visible to the logged-in session, as [{id, type, name, username}]. Use it to find the chat id or @username to pass as chat to tg_messages / tg_download. Optional filter does a case-insensitive substring match on name/username/id.
Inputs: filter.
tg_downloadDownload Telegram media from a chatA
Download media files from one chat (by id or @username) to a local directory and return the absolute paths of newly downloaded files. Use extensions (csv, e.g. 'xlsx,pdf') to fetch only certain file types; since_id for 'everything new after message X'; last_n for 'the latest N media messages' (default 100). Already-present files are skipped (--skip-same).
Inputs: chat (required), dest, last_n, since_id, +1 more.
tg_download_urlDownload Telegram media by t.me linkA
Download the media of specific Telegram messages given their t.me links (e.g. https://t.me/channel/123) and return the absolute paths of newly downloaded files. Use when you already have message links rather than a chat to scan. Already-present files are skipped (--skip-same).
Inputs: urls (required), dest, extensions.
tg_messagesRead recent Telegram messagesA
Export recent media messages from one chat (by id or @username) and return them as compact {id, date, file, text} objects — newest range exported via tdl. Use last_n for 'the last N media messages', or since_id to fetch only messages after a known message id (incremental reads). Read-only.
Inputs: chat (required), last_n, since_id, with_text.
tg_statusTelegram session statusA
Check whether the local tdl Telegram session is logged in and usable. Call this first if another tg_* tool fails or before starting Telegram work. Never errors — returns {logged_in:false, hint} when the session is missing.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
tg_messages and tg_download both center on media messages but are distinguished by one returning read-only metadata vs. the other downloading files. tg_download vs tg_download_url are clearly separated by input type (chat scan vs. specific t.me links), though the overlap between listing and downloading media could cause occasional misselection.
All tools share the tg_ prefix and are readable, but the suffix convention mixes nouns (chats, messages, status) with verbs (download, download_url), so it is not a strict verb_noun pattern. Still predictable enough that intent is clear.
Five tools is well-scoped for a Telegram media export/download utility. Each tool earns its place: discovery, metadata listing, two download paths, and a session check.
The surface covers the read-only media lifecycle: find chats, list media, download by chat or by link, and verify session. Gaps exist (no text/non-media message export, no search), but they are minor for the apparent media-export scope.
Maintenance
Related MCP Connectors
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only Telegram MCP server that retrieves messages from your DMs, groups, and channels, enabling Claude to generate executive briefings from Telegram conversations.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants like Claude to read, search, and send messages through your personal Telegram account via MCP tools.MIT
- AlicenseBqualityDmaintenanceProvides read-only access to Telegram chats, allowing AI agents to list chats, read messages, and search within chats via local MCP.14MIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude or other MCP clients to exchange files and notes through a personal Telegram bot and to read, search, and download from chats using read-only account access without sending, editing, deleting, or marking messages as read.1MIT