mcp-telegram-local

mcp-telegram-local

A local MCP (Model Context Protocol) server that connects Claude 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.

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) 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 — free, takes 2 minutes (see below)

---

Quick start

Option A — Web panel (recommended)

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

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

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:

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

You can also add it manually by running:

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:

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):

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

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