telegram-mcp

Drive Telegram as your own account from any MCP client — not a bot.

An MCP server that connects an AI agent to Telegram through your real user account over MTProto (via GramJS), authenticated with a saved session string. Because it acts as you and not a bot, it can read and search chat history and message anyone — things the Bot API cannot do.

It exposes 11 focused tools over stdio for sending, reading, searching, and managing messages, chats, and files.

Features

• You, not a bot — message people who never contacted you and post to any chat you belong to.

• Read & search history — pull recent messages or full-text search a conversation.

• Send anything — text with Markdown/HTML, replies, files by local path or URL.

• Manage messages — edit, delete (for everyone or just you), and forward across chats.

• Discover chats — list your dialogs with unread counts and resolve @username → id.

• Safe by default — returned content is sanitized against prompt injection; the client stays silent on stdout so it never corrupts the protocol stream.

Related MCP server: mcp-telegram

Prerequisites

• Node.js ≥ 22.14

• A Telegram account

• An api_id and api_hash from my.telegram.org/apps (these identify the app, not your account)

Installation

git clone https://github.com/naim30/telegram-mcp.git
cd telegram-mcp
npm install
npm run build

Configuration

Copy the example environment file and add your app credentials:

cp .env.example .env

*Set TELEGRAM_SESSION after running the login step below.

Login

Generate a session string once. The script prompts for your phone number, the login code Telegram sends you, and your two-factor password if you have one:

npm run login

Copy the printed string into .env as TELEGRAM_SESSION=.... That's it — the session is reused on every start, so you never log in again.

Connect to 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",
        "TELEGRAM_SESSION": "1BQANOTEuMTA...",
        "TELEGRAM_DEFAULT_CHAT": "me"
      }
    }
  }
}

Values in env override .env. The server connects to Telegram lazily on the first tool call and reuses one authorized client for its lifetime.

Tools

How it works

MCP client ──stdio──▶ server.ts ──▶ tool handler ──▶ GramJS client ──▶ Telegram (MTProto)
                                          │
                                          └─▶ serialize + sanitize ──▶ JSON result

src/
  server.ts          Registers all tools, connects the stdio transport
  login.ts           `npm run login` — interactive session-string generator
  config/config.ts   Typed environment config (envalid + dotenv)
  lib/
    client.ts        Lazy, authorized GramJS client
    register-tool.ts  Wraps each tool: JSON output, errors → isError
    sanitize.ts      Strips control/zero-width characters from returned text
    serialize.ts     Compact, BigInt-safe summaries of GramJS objects
    fields.ts        Shared zod input fields
  tools/             account · messages · files (one object per tool)

Scripts

npm run build    # Compile TypeScript to dist/
npm run login    # Generate a session string
npm start        # Run the server (needs a valid .env)

Acknowledgements

Built on GramJS and the Model Context Protocol SDK. The content-sanitization approach is adapted from the Telethon-based chigwell/telegram-mcp.