MCP Telegram

Hosted version available! Don't want to self-host? Use mcp-telegram.com -- connect Telegram to Claude.ai in 30 seconds with QR code. No API keys needed.

An MCP (Model Context Protocol) server that connects AI assistants like Claude to Telegram via the MTProto protocol. Unlike bots, this runs as a userbot -- it operates under your personal Telegram account using GramJS, giving full access to your chats, contacts, and message history.

Features

• MTProto protocol -- direct Telegram API access, not the limited Bot API
• Userbot -- operates as your personal account, not a bot
• 20 tools -- messaging, chat management, media, contacts, and more
• QR code login -- authenticate by scanning a QR code in the Telegram app
• Session persistence -- login once, stay connected across restarts
• Human-readable output -- sender names are resolved, not just numeric IDs
• Works with any MCP client -- Claude Code, Claude Desktop, Cursor, VS Code, Mastra, etc.

Prerequisites

• Node.js 18 or later
• Telegram API credentials -- API_ID and API_HASH from my.telegram.org

Quick Start

1. Get Telegram API credentials

1. Go to my.telegram.org and log in with your phone number.
2. Navigate to API development tools.
3. Create a new application (any name and platform).
4. Copy the App api_id and App api_hash.

2. Login

TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login

A QR code will appear in the terminal. Open Telegram on your phone, go to Settings > Devices > Link Desktop Device, and scan the code. The session is saved to ~/.telegram-session and reused automatically.

3. Add to Claude

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

That's it! Ask Claude to run telegram-status to verify.

Installation Options

npx (recommended, zero install)

No need to clone or install anything. Just use npx @overpod/mcp-telegram.

Global install

npm install -g @overpod/mcp-telegram
mcp-telegram          # run server
mcp-telegram login    # QR login

From source

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

Usage with MCP Clients

Claude Code (CLI)

claude mcp add telegram -s user \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -- npx @overpod/mcp-telegram

Claude Desktop

1. Open your config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Telegram server:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["@overpod/mcp-telegram"],
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

3. Restart Claude Desktop.

4. Ask Claude: "Run telegram-login" -- a QR code will appear. If the image is not visible, Claude will provide a browser link to view the QR code. Scan it in Telegram (Settings > Devices > Link Desktop Device).

5. Ask Claude: "Run telegram-status" to verify the connection.

Note: No terminal required! Login works entirely through Claude Desktop.

Cursor / VS Code

Add the same JSON config above to your MCP settings (Cursor Settings > MCP, or VS Code MCP config).

Mastra

import { MCPClient } from "@mastra/mcp";

const telegramMcp = new MCPClient({
  id: "telegram-mcp",
  servers: {
    telegram: {
      command: "npx",
      args: ["@overpod/mcp-telegram"],
      env: {
        TELEGRAM_API_ID: process.env.TELEGRAM_API_ID!,
        TELEGRAM_API_HASH: process.env.TELEGRAM_API_HASH!,
      },
    },
  },
});

Available Tools

Connection

Messaging

Reading

Chat Management

User Info

Media

Tool Parameters

Common patterns

Most tools accept chatId as a string -- either a numeric ID (e.g., "-1001234567890") or a username (e.g., "@username").

telegram-send-message

telegram-list-chats

telegram-read-messages

telegram-send-file

telegram-download-media

telegram-forward-message

telegram-edit-message

telegram-delete-message

telegram-pin-message

telegram-search-messages

telegram-search-chats

telegram-get-chat-members

telegram-get-contacts

telegram-get-profile

telegram-get-unread

Development

npm run dev        # Start with file watching (tsx)
npm start          # Start the MCP server
npm run login      # QR code login in terminal
npm run build      # Compile TypeScript
npm run lint       # Check code with Biome
npm run lint:fix   # Auto-fix lint issues
npm run format     # Format code with Biome

Project Structure

src/
  index.ts            -- MCP server entry point, 20 tool definitions
  telegram-client.ts  -- TelegramService class (GramJS wrapper)
  qr-login-cli.ts     -- CLI utility for QR code login

Tech Stack

• TypeScript -- ES2022, ESM modules
• GramJS (telegram) -- Telegram MTProto client
• @modelcontextprotocol/sdk -- MCP server framework
• Zod -- Runtime schema validation for tool parameters
• Biome -- Linter and formatter
• tsx -- TypeScript execution without a build step
• dotenv -- Environment variable management

Security

• API credentials are stored in .env (gitignored)
• Session is stored in .telegram-session (gitignored)
• Phone number is not required -- QR-only authentication
• This is a userbot (personal account), not a bot -- respect the Telegram Terms of Service

License

MIT