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