telegram-mcp-server

A local, read-only, folder-scoped MCP server that lets an AI agent (Claude Code, etc.) read your personal Telegram chats — but only the chats inside an allowlist of Telegram folders. No send/edit/delete capability exists.

Built for a common use case: let an agent read your client/lead conversations and pull out tasks, without giving it the keys to your whole Telegram.

⚠️ This logs in as your personal Telegram account via the official MTProto API (GramJS). Automating a user account is a grey area under Telegram's ToS; the risk is low for read-only use but not zero. Use on your own account.

How it stays safe

• Read-only. The server registers four tools, all read-only. There is no tool that can send, edit, or delete anything.
• Folder-scoped. Only chats inside the folders listed in config.json (allowedFolders) are reachable. Every tool resolves the requested chat against that allowlist and refuses anything outside it. Chats in your other folders (family, personal, etc.) are physically unreachable.
• Secrets stay local. api_id/api_hash live in config.json (gitignored). The session string — which grants full account access — is stored in the macOS Keychain, never on disk, never in git.

Requirements

• Bun (runs the TypeScript directly)
• macOS (uses the Keychain via the security CLI for session storage)
• A Telegram account, and an api_id / api_hash from https://my.telegram.org

Setup

# 1. install
bun install

# 2. configure
cp config.example.json config.json
#   edit config.json: apiId, apiHash, allowedFolders (exact Telegram folder names)

# 3. log in (QR — the reliable method; see note below)
bun run qr
#   On your phone: Telegram -> Settings -> Devices -> Link Desktop Device -> scan the QR

# 4. verify which folders/chats resolved
bun run folders

# 5. register with your MCP client (Claude Code example, user scope):
claude mcp add telegram -s user -- bun run "$(pwd)/src/server.ts"

Why QR login, not the SMS/app code

bun run login (phone + code) often fails: Telegram frequently accepts the SendCode request and reports "code sent to app", but never actually delivers the code (and offers no SMS fallback) for third-party API logins — especially with a freshly created api_id. bun run qr sidesteps this entirely: the login is approved from your already-authorized phone, so no code delivery is needed. Use QR first.

Tools

Tool	What it does
tg_list_folders	List allowed folders + resolved chat counts
tg_list_chats	List chats in allowed folders (optionally one folder)
tg_read_chat	Recent messages from one allowed chat
tg_search	Search messages across allowed chats / one folder / one chat

Troubleshooting

• A folder shows 0 chats → its name in config.json doesn't match Telegram exactly. Run bun run folders; if needed, temporarily inspect all folder titles (the diagnose output lists matched ones). Names are case-insensitive but must otherwise match (watch for typos / emoji / extra words).
• FLOOD_WAIT_N → too many login attempts; wait N seconds. Don't spam retries — each one extends the window.
• CHANNEL_PRIVATE skipped → a private channel you've left/been removed from can't be resolved; it's skipped, harmless.
• Login code never arrives → use bun run qr (see above).

Files

src/
  server.ts      MCP server (4 read-only tools)
  client.ts      GramJS client + folder allowlist (the privacy boundary)
  qr-login.ts    QR-code login (recommended)
  login.ts       phone+code login (fallback, with 'sms' resend)
  config.ts      loads config.json
  keychain.ts    session string <-> macOS Keychain
  diagnose.ts    'bun run folders' — show allowed folders + counts
  probe.ts       'bun run probe +NUMBER' — dump raw SendCode response

License

MIT