How do I install Tdl?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Tdl need an API key?

The publisher lists these environment variables: TDL_BIN, TDL_NS.

When was Tdl last checked?

Last checked 2026-11-10. Read-only Telegram MCP server wrapping the tdl CLI: list chats, read messages, download media.

Tdl MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Credentials from the publisher

TDL_BIN — Path to the tdl binary (default: tdl on PATH, falling back to /opt/homebrew/bin/tdl)
TDL_NS — tdl namespace passed as -n on every call, for separate Telegram accounts/sessions

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1TDL_BIN=<value> TDL_NS=<value> claude mcp add io.github.rixile9999-tdl-mcp -- npx -y tdl-mcp@1.1.0

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.rixile9999-tdl-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ],9      "env": {10        "TDL_BIN": "<value>",11        "TDL_NS": "<value>"12      }13    }14  }15}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 1.1.0
API key

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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_hash setup. Login is handled once, by you, in your terminal with tdl 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-same deduplication.
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→  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 | iex

Any 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 qr

Scan 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-mcp

Claude 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
`tg_status`	—	Checks whether the tdl session is logged in. Never errors: returns `{logged_in:true, chats:N}` or `{logged_in:false, hint}`.
`tg_chats`	`filter?`	Lists dialogs as `[{id, type, name, username}]`; `filter` is a case-insensitive substring match on name/username/id.
`tg_messages`	`chat`, `last_n?` (default 50, max 500), `since_id?`, `with_text?` (default true)	Exports recent media messages from a chat as compact `{id, date, file, text}` objects (at most 200 returned; truncation is noted). `since_id` fetches only messages after a known id — handy for incremental reads.
`tg_download`	`chat`, `since_id?`, `last_n?` (default 100), `extensions?` (csv, e.g. `"xlsx,pdf"`), `dest?` (default `~/Downloads/telegram`)	Downloads media from a chat with `--skip-same`; returns absolute paths of newly downloaded files, or a friendly "no matching files" note.
`tg_download_url`	`urls` (array of `https://t.me/...` links), `extensions?`, `dest?`	Downloads the media of specific messages by link. Validates every url starts with `https://t.me/`.

chat accepts either a numeric id or an @username/domain, exactly as shown by tg_chats.

Environment variables

Variable	Effect
`TDL_BIN`	Path to the tdl binary. Default: `tdl` on `PATH`, falling back to `/opt/homebrew/bin/tdl` (GUI-launched MCP hosts often don't inherit the Homebrew `PATH`).
`TDL_NS`	tdl namespace, passed as `-n <ns>` on every call. Use it to keep separate Telegram accounts/sessions apart.

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-version pins the tdl release this package is tested against.
scripts/contract.mjs verifies — 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 smoke spawns the server over stdio and checks the tool catalog, tg_status shape, and input validation — passes whether or not you are logged in.
npm run contract checks 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 ~/.tdl is 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-mcp never reads or transmits the session itself; it only runs the tdl binary 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).

Tdl

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Tdl?

Does Tdl need an API key?

What transport does Tdl use?

When was Tdl last checked?

Documentation

tdl-mcp

Why tdl-mcp?

Quick start

1. Install tdl

2. Log in to Telegram (once)

3. Add the server to your MCP host

4. Try it

Tools

Environment variables

Compatibility & staying up to date

Development

Security notes

Telegram terms-of-service note

License