# mcp-telegram-local

A **local MCP (Model Context Protocol) server** that connects [Claude](https://claude.ai) to your **personal Telegram account** using MTProto — the same encrypted protocol used by Telegram's own apps.

Claude gets 11 tools and 4 resources to read messages, search chats, send replies, forward files, and more — all through your real Telegram account, not a bot.

```bash
npx mcp-telegram-local
```

---

## What makes this different

Most Telegram integrations use the Bot API, which requires a separate bot account and can't access your personal chats. This server uses **MTProto** (via [gramjs](https://github.com/gram-js/gramjs)) to log in as **you** — the same way the official Telegram desktop app works. Claude sees exactly what you see: all your chats, groups, channels, contacts, and message history.

---

## Privacy & security

- **MTProto encryption.** All traffic between your computer and Telegram's servers is encrypted using MTProto — Telegram's own protocol. From Telegram's perspective, this is just another device you're logged into.
- **100% local.** Your `api_id`, `api_hash`, and session file live only on your computer at `~/.mcp-telegram/` with `600` permissions (owner read/write only). Nothing is sent to Anthropic, npm, or any third party — only to Telegram's own servers.
- **Claude runs it locally.** When Claude Code uses this server, it spawns `npx mcp-telegram-local serve` as a local process on your machine. The MCP communication happens over stdio — no network port is opened, no data leaves your computer.
- **Session = login.** The saved session is equivalent to a logged-in Telegram session. Keep `~/.mcp-telegram/session.json` private. To revoke it, run `npx mcp-telegram-local logout` — this signs the session out on Telegram's side and deletes the local file.

---

## Requirements

- **Node.js 18 or later**
- **Telegram account**
- **`api_id` and `api_hash`** from [my.telegram.org](https://my.telegram.org) — free, takes 2 minutes (see below)

---

## Quick start

### Option A — Web panel (recommended)

```bash
npx mcp-telegram-local ui
```

This opens a local web page at `http://127.0.0.1:8765` (only accessible from your computer). From there you can:

1. Enter your `api_id` and `api_hash`
2. Log in via **QR code** (scan with your phone) or **phone number** (code sent via SMS or Telegram)
3. Handle **2FA password** if you have one enabled (wrong password can be re-entered, up to 3 attempts)
4. Click **"Add to Claude Code"** to register the server automatically
5. See example prompts you can use with Claude right away

After adding to Claude Code, restart Claude Code and type `/mcp` — you should see `telegram` listed as a connected server.

### Option B — Terminal login

```bash
npx mcp-telegram-local auth
```

Walks you through login interactively in the terminal (phone number or QR code printed as ASCII art), then automatically registers the server in Claude Code.

---

## Getting api_id and api_hash

You need these once. They identify your app to Telegram and are stored locally.

1. Open **https://my.telegram.org** and log in with your phone number
2. Click **"API development tools"**
3. Fill in any app name and short name (e.g. `MyApp` / `myapp`) — the values don't matter
4. Copy the **`api_id`** (a number) and **`api_hash`** (a long hex string)

Paste them into the web panel or terminal when prompted. They're saved to `~/.mcp-telegram/config.json` and never needed again.

---

## All commands

```bash
npx mcp-telegram-local              # Show this command list
npx mcp-telegram-local ui           # ⭐ Open the web control panel
npx mcp-telegram-local auth         # Log in via terminal + auto-add to Claude Code
npx mcp-telegram-local status       # Check if your session is valid
npx mcp-telegram-local add_mcp      # Register server in Claude Code (no re-login)
npx mcp-telegram-local logout       # Sign out of Telegram + delete local session
npx mcp-telegram-local delete_key   # Delete api_id/api_hash + sign out (full reset)
npx mcp-telegram-local config       # Print the Claude Code config JSON snippet
npx mcp-telegram-local serve        # Force MCP server mode on stdio (used by Claude)
npx mcp-telegram-local help         # Show help
```

---

## How Claude Code uses this server

Once registered, Claude Code automatically starts `npx mcp-telegram-local serve` as a background process whenever it needs Telegram access. The server communicates over **stdio** (standard input/output) using the MCP protocol — no web server, no open ports, no background daemon to manage. It starts on demand and exits when Claude is done.

The config Claude Code stores looks like this:

```json
{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["mcp-telegram-local", "serve"]
    }
  }
}
```

You can also add it manually by running:

```bash
claude mcp add --scope user telegram -- npx mcp-telegram-local serve
```

---

## MCP tools available to Claude

| Tool | Parameters | What it does |
|---|---|---|
| `get_dialogs` | `limit`, `offset` | List your chats and channels |
| `get_messages` | `chat_id`, `limit` | Fetch message history from a chat |
| `search_messages` | `query`, `chat_id?`, `limit` | Search messages globally or in a specific chat |
| `get_unread` | `max_chats`, `max_messages_per_chat` | Fetch all unread messages across chats |
| `send_message` | `chat_id`, `text` | Send a text message |
| `reply_to_message` | `chat_id`, `message_id`, `text` | Reply to a specific message |
| `forward_message` | `from_chat`, `to_chat`, `message_id` | Forward a message between chats |
| `download_file` | `chat_id`, `message_id`, `include_base64?` | Download a file or photo from a message |
| `send_file` | `chat_id`, `file_path`, `caption?` | Send a file from your computer |
| `get_contacts` | — | List your Telegram contacts |
| `get_chat_members` | `chat_id`, `limit` | List members of a group or channel |

> `chat_id` accepts a numeric ID, `@username`, or a `t.me/...` link.

## MCP resources available to Claude

| URI | Description |
|---|---|
| `telegram://dialogs` | All your dialogs/chats |
| `telegram://chat/{id}` | A specific chat with recent messages |
| `telegram://unread` | All unread messages |
| `telegram://me` | Your Telegram profile |

---

## What you can ask Claude

Once connected, just describe what you want in plain English:

- *"Summarize the last 50 messages from my chat with Alex"*
- *"Reply to Maria that I'll be there at 7pm"*
- *"Show me all unread messages and tell me which ones are urgent"*
- *"Search my chats for any messages about the contract"*
- *"Forward the last message from @news_channel to my Saved Messages"*
- *"Send the file report.pdf to the Work group"*
- *"Write a digest of @somechannel posts from the last week"*
- *"Who messaged me today?"*

---

## Local data storage

All data is stored locally with restrictive file permissions:

```
~/.mcp-telegram/
├── config.json     # api_id and api_hash
├── session.json    # gramjs session string (equivalent to a Telegram login)
└── downloads/      # files downloaded via the download_file tool
```

To fully reset everything:
```bash
npx mcp-telegram-local delete_key
```

This revokes the session on Telegram's servers, deletes `session.json`, and deletes `config.json`. You'll start fresh next time.

To only sign out (keep api credentials):
```bash
npx mcp-telegram-local logout
```

After logout, go to **Telegram → Settings → Devices** if you want to confirm the session was removed there too.

---

## Error handling

- **Expired session.** If your session expires (e.g. you signed out from another device), tools return a friendly error with instructions to run `npx mcp-telegram-local auth` again.
- **FLOOD_WAIT.** Telegram rate-limits heavy requests. Short waits are handled automatically by gramjs; longer waits (up to 5 minutes) are retried automatically by a built-in wrapper.
- **Wrong 2FA password.** The web panel lets you re-enter your 2FA password up to 3 times before giving up. The terminal login does the same.

---

## Development

```bash
git clone https://github.com/pokkop/mcp-telegram-local
cd mcp-telegram-local
npm install
npm run build        # compile TypeScript → dist/
npm run dev          # watch mode
node dist/index.js status
```

Source layout:

```
src/
├── index.ts             # entry point: CLI commands + MCP server on stdio
├── auth.ts              # terminal login (phone + QR), MTProto/privacy banner
├── web.ts               # local web panel HTTP server + gramjs login bridge
├── web-page.ts          # full SPA (HTML/CSS/JS) served by web.ts
├── client.ts            # TelegramClient wrapper, JSON serializers, logout
├── tools.ts             # all 11 MCP tools
├── resources.ts         # all 4 MCP resources
├── storage.ts           # ~/.mcp-telegram/ read/write helpers
├── claude.ts            # auto-registration with Claude Code
├── notice.ts            # English MTProto/privacy notices for terminal output
└── suppress-warnings.ts # suppresses gramjs's Node.js localStorage warning
```

TypeScript compiles to ESM (`"type": "module"`) targeting Node 18+. gramjs logging is fully silenced (`LogLevel.NONE`) to prevent any stray output from corrupting the MCP stdio stream.

---

## License

MIT