mcp-telegram (sparfenyuk)
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
- 190 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The session opens the account's private conversations: the assistant sees every dialog and message the server returns
- The API hash and sign-in session give access to the account, and a leaked hash cannot be reissued
Install
- Works in
- Services
Manual install
uv tool install git+https://github.com/sparfenyuk/mcp-telegramThe command from the docs; uv is required.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The session opens the account's private conversations: the assistant sees every dialog and message the server returns
- The API hash and sign-in session give access to the account, and a leaked hash cannot be reissued
This is third-party code. Review the repository files before installing.
What it does
The sparfenyuk MCP Telegram server connects an assistant to your personal Telegram account over the MTProto protocol. It is written in Python on top of Telethon and runs on your own computer. Two actions exist today, both read-only: listing dialogs (chats, channels, groups) and fetching messages from a chosen dialog, optionally only the unread ones. The one practical scenario in the docs is asking the assistant to summarize unread messages. Marking a dialog as read, selecting messages by date, downloading media, a contact list and drafts are on the author's roadmap and not built yet. The server has no way to send or delete messages, which suits anyone who only needs an overview of their conversations.
Who it is for. For Claude Desktop users who want summaries of piled-up Telegram messages without letting the assistant write in their name.
Good fit when
- You need a summary of unread messages from work chats and channels after a weekend
- You want to see your dialogs and groups inside the assistant window
- You want a cautious first MCP for Telegram: the server only reads and has no send action
- You are testing MCP tools from the command line: uv run cli.py list-tools prints the tools and call-tool runs any of them
Not a fit when
- The assistant must send, edit or delete messages: the server has no such tools, other Telegram servers cover writing
- You need search by date, attachment downloads or a contact list: these are still on the author's roadmap
- You need a bot via the Bot API instead of a personal account: this server signs in by phone number
- The account must stay safe from restrictions: the author warns that misuse of the Telegram API may get it suspended
Example request
Show my unread Telegram messages and write a short summary for each chat.MCP
- Transport
- stdio
- Authentication
- API key
Environment variables
TELEGRAM_API_IDrequired- Numeric application API ID from my.telegram.org
TELEGRAM_API_HASHrequired, secret- Application API hash; Telegram does not let you reissue it
Limitations
You need an API ID and API hash from my.telegram.org, a phone number and the code Telegram sends. With two-factor authentication on, the account password is required too. The hash cannot be reissued, so keep it secret.
Python 3.11 or newer and the uv tool are required. The docs give a configuration example for Claude Desktop only; other clients are not mentioned. The example names the command mcp-server, while pyproject registers mcp-telegram: use that one.
The repository was last updated in March 2025. The author warns that breaking Telegram API rules may get an account suspended. Whether Telegram itself is reachable from Russia depends on the carrier and was not checked for this card.
How to disable. Remove the mcp-telegram block from claude_desktop_config.json. Sign out with mcp-telegram logout and delete the server with uv tool uninstall mcp-telegram.
FAQ
How do I install MCP Telegram in Claude Desktop?
Install uv, then run uv tool install git+https://github.com/sparfenyuk/mcp-telegram. Sign in with mcp-telegram sign-in using your API ID, API hash and phone number, enter the code from Telegram and add the server to claude_desktop_config.json with TELEGRAM_API_ID and TELEGRAM_API_HASH.
Can this MCP Telegram server send messages?
No. Access is read-only: the dialog list and messages of a dialog, including unread ones. Sending, drafts and marking as read are on the future list.
Where do I get an API ID and API hash for Telegram?
At my.telegram.org: sign in with your phone number, open API Development tools and create an application. Only the title and short name are needed. The hash cannot be reissued, so never publish it.
How does the sparfenyuk mcp-telegram differ from dryeab/mcp-telegram?
The sparfenyuk repository only reads dialogs and messages, while dryeab adds sending, editing, deleting, search, drafts and media download. The sparfenyuk server offers less, with less chance of an accidental write.
How do I sign out and remove MCP Telegram?
mcp-telegram logout ends the sign-in and uv tool uninstall mcp-telegram removes the server. Also delete the mcp-telegram block from claude_desktop_config.json.
Discussion
No questions or reviews yet.
Related
All Telegram toolsMCP Telegram with write access: the agent sends, edits and deletes messages, searches chats, keeps drafts and downloads media in your account over MTProto
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
A Telethon MCP server: the agent reads and sends messages and manages chats, contacts and folders in your Telegram account
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
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
Tracker report Telegram delivery MCP
Telegram Delivery MCP
A companion MCP server that takes a finished Yandex Tracker report and sends it to Telegram through an existing bot service
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| mcp-telegram (sparfenyuk) (this entry) | no | API key | 190 | |
| mcp-telegram (dryeab) | no | API key | 254 | another MCP Telegram server with sending, editing, deleting and search |
| Telegram MCP Server | no | API key | 1,920 | a Telethon server where the agent reads and sends messages and manages chats |
| Telegram API MCP | no | API key | 33 | works through the Bot API as a bot rather than a personal account |
README in short
The docs list the features (dialog and message listing done, the rest planned), the requirement (the uv tool), one-command installation, sign-in with API ID, API hash and phone, a Claude Desktop configuration example and a debugging section covering the CLI and MCP Inspector. A new tool needs an arguments class in tools.py and a registered function.