tg_meLABSCO SUMMARY
Five tools, and the unread filter is the one that makes it a daily habit.
Listing dialogs filtered to unread turns a scattered inbox into something summarisable in one pass, and marking read afterwards keeps the state honest. Because it authenticates as you rather than as a bot, it sees everything you see — worth reading Telegram's API terms before you point automation at it, as the project itself asks.
What it is
A Telegram bridge for AI assistants, running as your account through the Telegram API rather than as a bot.
What you get
- tg_me — your current account information
- tg_dialogs — your chat list, with an optional unread filter
- tg_dialog — messages from a specific chat
- tg_read — mark a dialog as read
- tg_send — send a draft message to any dialog
Requirements
An API ID and hash from my.telegram.org, then a one-time telegram-mcp auth with your phone number and the code Telegram sends; add --password if you have 2FA. TG_APP_ID and TG_API_HASH go in the client config. Install by Homebrew, npx @chaindead/telegram-mcp, a release binary, or go install with Go 1.24 or later. Clients that reject JSON Schema Draft 2020-12, such as VS Code, can be handled with TG_SCHEMA_VERSION set to the Draft-07 URL.
Setup effort
Follow the published steps
USE CASES
01
Catching up after a day away
List dialogs with unread messages, read the ones that matter, and mark the rest read.
02
Drafting a reply you will send yourself
Have the assistant compose it into the chat as a draft rather than firing it off.
03
Working out how to organise your chats
Analyse your dialog list and get a folder structure proposed from what is actually there.
04
Making sure nothing went unanswered
Scan chats for questions that never got a reply.
5 tools
Listed in project docs. Your client may show a different list.
tg_dialogstg_readtg_dialogtg_sendBEFORE YOU INSTALL
What to know first
Tools you get
5 tools named in the project's documentation.
Requires
- npx on PATH — or the telegram-mcp binary from Homebrew, a release archive, or go install (Go 1.24 or later)
- TG_APP_ID and TG_API_HASH: your API ID and hash from my.telegram.org, set in the client configuration
- A one-time auth login with your Telegram phone number (and 2FA password, if enabled)
Where it runs
All 3 documented setups run the server on your machine.
INSTALLATION
Connect your client
Server setup
Get your API ID and API hash from https://my.telegram.org/auth.
Authorize once: run the command below with your API ID, API hash and phone number, then enter the code Telegram sends you. Add --password <2fa_password> if you have 2FA enabled, or --new to override an existing session.
TERMINAL
npx -y @chaindead/telegram-mcp auth --app-id <YOUR_APP_ID> --api-hash <YOUR_TG_API_HASH> --phone <YOUR_PHONE_NUMBER>Add the configuration from a client tab and restart the client. If you installed the telegram-mcp binary instead of using npx (brew install chaindead/tap/telegram-mcp, a release archive, or go install github.com/chaindead/telegram-mcp@latest with Go 1.24+), run the same auth command as telegram-mcp auth … and use the binary tabs.
MCP Clients
Claude Desktop — npx
CLAUDE DESKTOP — NPX · JSON
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": [
"-y",
"@chaindead/telegram-mcp"
],
"env": {
"TG_APP_ID": "<YOUR_TG_APP_ID>",
"TG_API_HASH": "<YOUR_TG_API_HASH>"
}
}
}
}Claude Desktop — binary
CLAUDE DESKTOP — BINARY · JSON
{
"mcpServers": {
"telegram": {
"command": "telegram-mcp",
"env": {
"TG_APP_ID": "<YOUR_TG_APP_ID>",
"TG_API_HASH": "<YOUR_TG_API_HASH>",
"PATH": "<YOUR_PATH_TO_TELEGRAM_MCP_BINARY_DIR>",
"HOME": "<YOUR_HOME>"
}
}
}
}Cursor — binary
CURSOR — BINARY · JSON
{
"mcpServers": {
"telegram-mcp": {
"command": "telegram-mcp",
"env": {
"TG_APP_ID": "<YOUR_TG_APP_ID>",
"TG_API_HASH": "<YOUR_TG_API_HASH>"
}
}
}
}Runs the telegram-mcp binary (Homebrew, a release archive or go install). If you set up with npx instead, the binary is not on your PATH — use the command and args from the Claude Desktop — npx tab.
