telegram-mcp

This MCP server logs in as your own Telegram account, over Telegram's native MTProto protocol (via GramJS). Acting as your user account, it can read and search your full history, message anyone, join chats, and manage your account — all driven from any MCP client.

It speaks the Model Context Protocol over stdio, so it plugs into Claude Desktop, Claude Code, or any MCP-compatible client, exposing 44 tools across seven domains.

Features

• User-account access — read and search your full history, and message anyone.

• 44 tools, 7 domains — account, users, messages, files, chats, groups, contacts.

• Read/write permission hints — every tool is annotated read or write (MCP readOnlyHint), so clients can auto-approve reads and gate writes.

• Login once — an interactive login saves a portable session to a gitignored file; the server reuses it forever. No password or session ever touches your MCP config.

• Safe by construction — returned text is sanitized against prompt injection, and results are compact JSON (never raw, circular GramJS objects).

Related MCP server: mcp-telegram

Requirements

• Node.js 22.14 or newer

• A Telegram account and API credentials (api_id + api_hash) from my.telegram.org/apps

Getting started

1. Install and build

npm install
npm run build

2. Configure credentials

Copy the example env file and fill it in:

cp .env.example .env

3. Log in

Run the interactive login once. It prompts for your phone number, the code Telegram sends you, and your two-factor password (if set):

npm run login

It saves the session to .telegram-session (in SESSION_PATH, or the project root by default) with owner-only 0600 permissions. The server reads it automatically on every start — you never log in again and never paste the session into any config.

4. Connect an MCP client

Point your client at the built server. Example .mcp.json:

{
  "mcpServers": {
    "telegram": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/telegram-mcp/dist/server.js"],
      "env": {
        "TELEGRAM_API_ID": "1234567",
        "TELEGRAM_API_HASH": "0123456789abcdef0123456789abcdef"
      }
    }
  }
}

That's it — ask your client to list your chats, search a conversation, or send a message.

Tools

All 44 tools live in src/tools/, one file per domain. Each is either a read (safe to auto-approve) or a write (mutates your account — gate it).

How it works

flowchart LR
    client(["MCP client<br/>Claude Desktop / Code"])
    client -- "request · stdio / JSON-RPC" --> server["server.ts"]
    server --> handler["tool handler"]
    handler -- "getClient()" --> gramjs["GramJS · MTProto<br/>→ Telegram"]
    gramjs -- "raw result" --> shape["serialize + sanitize"]
    shape -- "compact, safe JSON" --> client

• server.ts registers every tool and connects a StdioServerTransport.

• lib/client.ts lazily creates one shared, authenticated GramJS client on the first tool call and reuses it for the process lifetime (keeping the entity cache warm).

• Tool prose lives in YAML. Each tool's description and field docs are in src/prompts/*.yml (loaded via promptoro); the TypeScript holds only types and logic.

• Every result is mapped through serialize.ts (compact, BigInt-safe) and sanitize.ts (strips control/zero-width characters as a prompt-injection defense) — raw GramJS objects are never returned.

Security & safety

• .env and .telegram-session are gitignored. The session string is full access to your account — never commit, log, or share it.

• The login script writes the session file with 0600 (owner read/write only).

• Tools are annotated read vs write so your MCP client can auto-approve harmless reads while prompting for anything that changes your account.

Development

npm run build     # tsc -p . → dist/ (also copies prompt YAML)
npm start         # run dist/server.js (needs a valid .env)
npm run login     # regenerate the session string

Adding a tool: define it in the file for its group under src/tools/, add the matching src/prompts/<name>.yml, register it in src/server.ts, and rebuild. See CLAUDE.md for the full conventions.