Telegram MCP by chaindead
Telegram MCP
A Go MCP server for your Telegram account: the agent reads dialogs and unread messages, marks them read, leaves replies as drafts
- 350 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent reads your personal dialogs, groups and channels under your account, and the conversations reach the model
- The Telegram session is stored on disk, and anyone who gets it gets access to the account
- The author warns that misuse of the Telegram API may get the account suspended
Install
- Works in
- Services
Manual install
brew install chaindead/tap/telegram-mcpFor macOS and Linux. Then run telegram-mcp auth. Without Homebrew use npx -y @chaindead/telegram-mcp or download an archive from the releases.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent reads your personal dialogs, groups and channels under your account, and the conversations reach the model
- The Telegram session is stored on disk, and anyone who gets it gets access to the account
- The author warns that misuse of the Telegram API may get the account suspended
This is third-party code. Review the repository files before installing.
What it does
Telegram MCP bridges the Telegram API and an AI assistant. The server signs in to Telegram as you over MTProto using an app ID and API hash, so the agent sees your personal dialogs, groups and channels. There are five tools. `tg_me` shows the current account. `tg_dialogs` lists dialogs, optionally only those with unread messages. `tg_dialog` fetches messages from a specific dialog. `tg_read` marks a dialog as read. `tg_send` saves a message as a draft in a dialog. With this set the agent triages unread messages, prepares draft replies and finds questions nobody answered. Authorization is needed once: `telegram-mcp auth` asks for a phone number and a code from Telegram.
Who it is for. For people drowning in Telegram chats who want Claude or Cursor to sort unread messages and prepare reply drafts.
Good fit when
- Unread dialogs piled up during a vacation and you want a summary with the important ones on top
- You want drafts of replies to the latest messages in work chats that you review and send yourself
- You want to sort chats into folders and need the agent to propose a layout from their content
- You want to check whether any questions in your chats are still unanswered
- You need to follow a topic in one chat and be told about new messages
Not a fit when
- You need a bot: the server works over MTProto under your number and does not use the bot API
- You want messages sent automatically: `tg_send` only leaves a draft
- You cannot give an agent access to private conversations, work secrets and other people's data
- You need deleting and editing messages, searching chats and downloading files: the five-tool set does not include them
Example request
Show my unread Telegram dialogs, pick out the work ones and prepare a draft reply to the last question in the team chatMCP
- Transport
- stdio
- Authentication
- API key
Environment variables
TG_APP_IDrequired- Telegram app ID from my.telegram.org
TG_API_HASHrequired, secret- Telegram app API hash
TG_SCHEMA_VERSION- JSON Schema version when the client rejects 2020-12
Limitations
You need an app ID and API hash from my.telegram.org and a sign-in with a phone number and code. With two-factor protection on, add the `--password` flag to the sign-in command, and to replace a session add `--new`.
The author asks you to read the Telegram API terms of service first: misuse may get your account suspended. The server works under your personal number, so Telegram sees every agent action as yours.
Whether Telegram is reachable from Russia has not been checked.
How to disable. Remove the telegram block from your client settings and restart it. To close the session, open the active devices section in Telegram and end the app's session. If installed through Homebrew, uninstall with `brew uninstall telegram-mcp`.
FAQ
How do I connect Telegram MCP to Claude Desktop or Cursor?
Get an app ID and API hash at my.telegram.org and run `telegram-mcp auth --app-id <id> --api-hash <hash> --phone <number>`. Then add a block to the config with the command `telegram-mcp` and the environment variables `TG_APP_ID` and `TG_API_HASH`. For Claude Desktop also set `PATH` and `HOME`.
How do I run the server through npx?
With `npx -y @chaindead/telegram-mcp`. Authorization then looks like `npx -y @chaindead/telegram-mcp auth ...`, and the client config uses the command `npx` with the arguments `-y` and `@chaindead/telegram-mcp`. A Homebrew installer and prebuilt archives for macOS, Linux and Windows exist too.
Can the agent send messages without me?
No. The `tg_send` tool saves a draft in the dialog and you send it in the Telegram app. `tg_read` marks a dialog as read when the agent asks.
What if I have two-factor protection on?
Add `--password` with your cloud password to the authorization command. To replace an already saved session, add the `--new` flag.
How do I update the server?
A Homebrew install updates with `brew upgrade chaindead/tap/telegram-mcp`. When you run through `npx -y @chaindead/telegram-mcp`, the package comes from npm. Prebuilt archives are downloaded again from the releases page.
Discussion
No questions or reviews yet.
Related
All Telegram toolsA Telethon MCP server: the agent reads and sends messages and manages chats, contacts and folders in your Telegram account
MCP Telegram with write access: the agent sends, edits and deletes messages, searches chats, keeps drafts and downloads media in your account over MTProto
MCP Telegram for reading: the agent gets your account's dialog list and unread messages over MTProto and has no way to write on your behalf
Telegram API MCP
telegram-api-mcp
MCP server for the Telegram Bot API: messages, channels, forums, payments and long posts from a bot, with Telegram rate limits built in
TGStat MCP
tgstat-mcp
TGStat MCP server: Telegram channel and post search, subscriber and reach trends, ERR and mentions
Mail.ru MCP server and Telegram notifier
Mail Agent
An MCP server for Mail.ru email in Claude.ai, plus a separate Telegram bot that checks the inbox every 15 minutes and alerts on important messages
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Telegram MCP by chaindead (this entry) | no | API key | 350 | |
| Telegram MCP Server | no | API key | 1,933 | a Telethon server where the agent reads, sends messages and manages chats, contacts and folders |
| mcp-telegram (sparfenyuk) | no | API key | 190 | read-only: dialog list and unread messages over MTProto |
| Telegram API MCP | no | API key | 33 | a server for the Bot API that acts as a bot |
README in short
The description explains what MCP is and lists capabilities with example prompts in three groups: messages, organization and communication. Install options, the authorization steps, client setup and the JSON Schema version override follow.