telegram-mcp

Your Telegram account in an MCP client. Signs in as you, not as a bot: it reads your private chats, and anything it sends comes from you.

Install

Node 22+.

1. Get API keys: my.telegram.org → API development tools → create an app (platform Other, rest blank) → copy api_id and api_hash.

2. Sign in — once, in a terminal:

   TELEGRAM_API_ID=... TELEGRAM_API_HASH=... npx @vkruglikov/telegram-mcp login
   

   It asks for your phone, the code Telegram sends, and your 2FA password if you have one. This is a terminal command and not a tool on purpose — as a tool, the code and the password would pass through the model's context and land in chat logs.

3. Register the server:

   claude mcp add telegram \
     --env TELEGRAM_API_ID=... \
     --env TELEGRAM_API_HASH=... \
     -- npx -y @vkruglikov/telegram-mcp
   

   Clients that read a JSON config instead:

   {
     "mcpServers": {
       "telegram": {
         "command": "npx",
         "args": ["-y", "@vkruglikov/telegram-mcp"],
         "env": { "TELEGRAM_API_ID": "...", "TELEGRAM_API_HASH": "..." }
       }
     }
   }
   

4. Check: npx @vkruglikov/telegram-mcp status.

logout revokes the session server-side and deletes it locally.

Features

Your account:

list_chats	Dialogs, newest first, or only unread
search_chats	Find a dialog by name — Вадим also matches Vadim
get_history	Read a chat. Does not mark it read
search_messages	Full-text, one chat or the whole account
send_message / send_file	Delivered immediately, no undo
download_media	Save an attachment
mark_read	The only tool that marks anything read — the other side sees it
list_contacts	Saved contacts

All of Telegram, not just your chats:

search_public_chats	Channels, groups and people you have never opened
search_public_posts	Text of every public channel. A few free searches a day; the result says how many are left

Prompts, shown as slash commands: personalize, draft_reply, catch_up.

Drafting in your voice

1. Run /personalize. It calls sample_my_messages to collect messages you sent in recent private chats, then describes the patterns: languages and how you mix them, message length, greetings and sign-offs, punctuation you skip, which emoji and where, recurring phrasings, how formality shifts, and what you never do.
2. It shows the profile before saving. Edit or reject it.
3. Saved to ~/.telegram-mcp/style.md. Reconnect the server to load it.
4. /draft_reply <chat> [intent] writes in that voice and shows the draft. It never sends.

get_style_profile prints the profile, forget_style_profile deletes it.

The profile covers how you write, not what you think. Facts, opinions and commitments stay yours to supply.

Everything stays on your machine

Local process, straight to Telegram, no service in between. Everything lives in ~/.telegram-mcp:

• session.db — your login session
• style.md — your style profile, if you made one
• downloads/ — downloaded attachments

No telemetry, no account of ours, no third party. Credentials, session and messages go nowhere else.

Treat session.db like a password. It grants full access to your account without the password and without 2FA. Never copy it to another machine or into a repo. If it leaks, revoke it in Telegram → Settings → Devices. Deleting the folder by hand revokes nothing — use logout.

License

MIT