MCP Telegram

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

MCP Telegram demo — connect and summarize chats in Claude

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
Full-featured -- messaging, reactions, polls, scheduled messages, media, contacts, and more
Forum Topics -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
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, ChatGPT, 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

Go to my.telegram.org and log in with your phone number.
Navigate to API development tools.
Create a new application (any name and platform).
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 ~/.mcp-telegram/session and reused automatically.

Custom session path: set TELEGRAM_SESSION_PATH=/path/to/session to store the session file elsewhere.

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.

Multiple Accounts

Use TELEGRAM_SESSION_PATH to run separate Telegram accounts side by side:

# Login each account with a unique session path
TELEGRAM_API_ID=ID1 TELEGRAM_API_HASH=HASH1 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work npx @overpod/mcp-telegram login
TELEGRAM_API_ID=ID2 TELEGRAM_API_HASH=HASH2 TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal npx @overpod/mcp-telegram login

Then add each as a separate MCP server:

claude mcp add telegram-work -s user \
  -e TELEGRAM_API_ID=ID1 \
  -e TELEGRAM_API_HASH=HASH1 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-work \
  -- npx @overpod/mcp-telegram

claude mcp add telegram-personal -s user \
  -e TELEGRAM_API_ID=ID2 \
  -e TELEGRAM_API_HASH=HASH2 \
  -e TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-personal \
  -- npx @overpod/mcp-telegram

Each account gets its own session file — no conflicts.

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

Open your config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Telegram server:

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

Restart Claude Desktop.
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).
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

Tool	Description
`telegram-status`	Check connection status and current account info
`telegram-login`	Authenticate via QR code

Messaging

Tool	Description
`telegram-send-message`	Send a text message to a chat
`telegram-send-file`	Send a file (photo, document, video, etc.) to a chat
`telegram-send-reaction`	Send or remove an emoji reaction on a message
`telegram-send-scheduled`	Schedule a message for future delivery
`telegram-create-poll`	Create a poll (multiple choice or quiz mode)
`telegram-edit-message`	Edit a previously sent message
`telegram-delete-message`	Delete messages in a chat
`telegram-forward-message`	Forward messages between chats

Reading

Tool	Description
`telegram-list-chats`	List recent dialogs with unread counts, bot/contact markers
`telegram-read-messages`	Read recent messages from a chat
`telegram-search-chats`	Search for chats, users, or channels by name
`telegram-search-messages`	Search messages in a chat by text
`telegram-get-unread`	Get chats with unread messages; forums show per-topic unread breakdown
`telegram-get-contact-requests`	Get incoming messages from non-contacts with preview

Forum Topics

Tool	Description
`telegram-list-topics`	List forum topics in a group with unread counts and status
`telegram-read-topic-messages`	Read messages from a specific forum topic

Chat Management

Tool	Description
`telegram-mark-as-read`	Mark a chat as read
`telegram-get-chat-info`	Get detailed info about a chat (name, type, members, bot/contact status)
`telegram-get-chat-members`	List members of a group or channel
`telegram-join-chat`	Join a group or channel by username or invite link
`telegram-pin-message`	Pin a message in a chat
`telegram-unpin-message`	Unpin a message in a chat

Contacts & Moderation

Tool	Description
`telegram-add-contact`	Add a user to your contacts (accept contact request)
`telegram-block-user`	Block a user from sending you messages
`telegram-report-spam`	Report a chat as spam to Telegram

User Info

Tool	Description
`telegram-get-contacts`	Get your contacts list with phone numbers
`telegram-get-profile`	Get detailed profile info for a user (bio, photo, last seen)

Media

Tool	Description
`telegram-download-media`	Download media from a message to a local file

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

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`text`	string	yes	Message text
`replyTo`	number	no	Message ID to reply to
`parseMode`	`"md"` / `"html"`	no	Message formatting mode
`topicId`	number	no	Forum topic ID to send into (for groups with Topics)

telegram-list-topics

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username (group with Topics enabled)
`limit`	number	no	Max topics to return (default: 100)

telegram-read-topic-messages

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`topicId`	number	yes	Topic ID (from `telegram-list-topics`)
`limit`	number	no	Number of messages (default: 20)
`offsetId`	number	no	Message ID for pagination

telegram-list-chats

Parameter	Type	Required	Description
`limit`	number	no	Number of chats to return (default: 20)
`offsetDate`	number	no	Unix timestamp for pagination
`filterType`	`"private"` / `"group"` / `"channel"` / `"contact_requests"`	no	Filter by chat type

telegram-read-messages

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`limit`	number	no	Number of messages (default: 10)
`offsetId`	number	no	Message ID for pagination

telegram-send-file

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`filePath`	string	yes	Absolute path to the file
`caption`	string	no	File caption

telegram-download-media

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`messageId`	number	yes	Message ID containing media
`downloadPath`	string	yes	Absolute path to save the file

telegram-forward-message

Parameter	Type	Required	Description
`fromChatId`	string	yes	Source chat ID or @username
`toChatId`	string	yes	Destination chat ID or @username
`messageIds`	number[]	yes	Array of message IDs to forward

telegram-edit-message

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`messageId`	number	yes	ID of the message to edit
`text`	string	yes	New message text

telegram-delete-message

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`messageIds`	number[]	yes	Array of message IDs to delete

telegram-pin-message

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`messageId`	number	yes	Message ID to pin
`silent`	boolean	no	Pin without notification (default: false)

telegram-join-chat

Parameter	Type	Required	Description
`target`	string	yes	Username (@group), link (t.me/group), or invite link (t.me/+xxx)

telegram-send-reaction

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`messageId`	number	yes	Message ID to react to
`emoji`	string	no	Reaction emoji (e.g. 👍❤️🔥😂🎉). Omit to remove reaction

telegram-send-scheduled

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username (use `"me"` or `"self"` for Saved Messages)
`text`	string	yes	Message text
`scheduleDate`	number	yes	Unix timestamp when to send (must be in the future)
`replyTo`	number	no	Message ID to reply to
`parseMode`	`"md"` / `"html"`	no	Message formatting mode

telegram-create-poll

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`question`	string	yes	Poll question
`answers`	string[]	yes	Answer options (2-10 items)
`multipleChoice`	boolean	no	Allow multiple answers (default: false)
`quiz`	boolean	no	Quiz mode with one correct answer (default: false)
`correctAnswer`	number	no	Index of correct answer, 0-based (required for quiz mode)

telegram-search-messages

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`query`	string	yes	Search text
`limit`	number	no	Max results (default: 20)

telegram-search-chats

Parameter	Type	Required	Description
`query`	string	yes	Search query (name or username)
`limit`	number	no	Max results (default: 10)

telegram-get-chat-members

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username
`limit`	number	no	Number of members (default: 50)

telegram-get-contacts

Parameter	Type	Required	Description
`limit`	number	no	Number of contacts (default: 50)

telegram-get-profile

Parameter	Type	Required	Description
`userId`	string	yes	User ID or @username

telegram-get-unread

Parameter	Type	Required	Description
`limit`	number	no	Number of unread chats (default: 20)

telegram-get-contact-requests

Parameter	Type	Required	Description
`limit`	number	no	Number of contact requests (default: 20)

telegram-add-contact

Parameter	Type	Required	Description
`userId`	string	yes	User ID or @username to add
`firstName`	string	yes	First name for the contact
`lastName`	string	no	Last name for the contact
`phone`	string	no	Phone number for the contact

telegram-block-user

Parameter	Type	Required	Description
`userId`	string	yes	User ID or @username to block

telegram-report-spam

Parameter	Type	Required	Description
`chatId`	string	yes	Chat ID or @username to report

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, 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 ~/.mcp-telegram/session with 0600 permissions (owner-only access)
Session directory is created with 0700 permissions
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

MCP Telegram

MCP Telegram

Features

Prerequisites

Quick Start

1. Get Telegram API credentials

2. Login

3. Add to Claude

Multiple Accounts

Installation Options

npx (recommended, zero install)

Global install

From source

Usage with MCP Clients

Claude Code (CLI)

Claude Desktop

Cursor / VS Code

Mastra

Available Tools

Connection

Messaging

Reading

Forum Topics

Chat Management

Contacts & Moderation

User Info

Media

Tool Parameters

Common patterns

telegram-send-message

telegram-list-topics

telegram-read-topic-messages

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-join-chat

telegram-send-reaction

telegram-send-scheduled

telegram-create-poll

telegram-search-messages

telegram-search-chats

telegram-get-chat-members

telegram-get-contacts

telegram-get-profile

telegram-get-unread

telegram-get-contact-requests

telegram-add-contact

telegram-block-user

telegram-report-spam

Development

Project Structure

Tech Stack

Security

License

Máy chủ liên quan

WeCom Bot

ClickSend MCP Server

WhatsApp Web MCP

Slack User

WhatsApp MCP server by Kapso

X MCP Server

mpc-bridge

mcp-bitrix24

FastIntercom

Gmail MCP Server