# 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](https://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:

   ```sh
   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:

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

   Clients that read a JSON config instead:

   ```json
   {
     "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