MCP-Telegram

MCP-Telegram

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.

Category
访问服务器

README

MCP Telegram

npm npm downloads Node.js TypeScript MCP SDK License: MIT mcp-telegram MCP server

📖 Documentation · ☁️ Cloud version — connect Telegram to Claude.ai or ChatGPT in 30 seconds with QR code, no API keys needed.

<p align="center"> <img src="assets/demo.gif" alt="MCP Telegram demo — connect and summarize chats in Claude" width="700"> </p>

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

  • Comprehensive tool coverage -- the most full-featured Telegram MCP server available (80+ tools)
  • 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, stickers, media, contacts, and more
  • Forum Topics -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
  • Stickers -- search sticker sets, browse installed/recent stickers, send stickers to any chat
  • Account management -- update profile, manage privacy settings, sessions, auto-delete timers
  • Global search -- search messages across all chats at once
  • Real-time polling -- fetch updates via stateless cursors; agent owns {pts, qts, date} state
  • Inline bots & buttons -- query inline bots, send results, press callback buttons
  • Stories -- read stories from peers, get story view stats
  • Admin controls -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests
  • Stats -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)
  • Boosts & Business -- boost status, boosters list, Telegram Business chat links
  • 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

  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 ~/.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.

Proxy Support

If Telegram is blocked or you're running in a containerized environment (Docker, K3s), use a SOCKS5 or MTProxy:

# SOCKS5 proxy
TELEGRAM_PROXY_IP=127.0.0.1 \
TELEGRAM_PROXY_PORT=10808 \
npx @overpod/mcp-telegram

# MTProxy
TELEGRAM_PROXY_IP=proxy.example.com \
TELEGRAM_PROXY_PORT=443 \
TELEGRAM_PROXY_SECRET=ee00000000000000000000000000000000 \
npx @overpod/mcp-telegram
Variable Description
TELEGRAM_PROXY_IP Proxy server address
TELEGRAM_PROXY_PORT Proxy server port
TELEGRAM_PROXY_SOCKS_TYPE 4 or 5 (default: 5)
TELEGRAM_PROXY_SECRET MTProxy secret (enables MTProxy mode)
TELEGRAM_PROXY_USERNAME Optional proxy auth
TELEGRAM_PROXY_PASSWORD Optional proxy auth

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

Pre-built binary (no runtime needed)

Download from Releases — standalone single-file binaries, zero dependencies:

Platform Server Login CLI
Linux x64 mcp-telegram-linux-x64 mcp-telegram-login-linux-x64
Linux ARM64 mcp-telegram-linux-arm64 mcp-telegram-login-linux-arm64
macOS x64 mcp-telegram-darwin-x64 mcp-telegram-login-darwin-x64
macOS ARM64 mcp-telegram-darwin-arm64 mcp-telegram-login-darwin-arm64
Windows x64 mcp-telegram-windows-x64.exe mcp-telegram-login-windows-x64.exe 
# Download (example for Linux x64)
curl -L -o mcp-telegram https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-linux-x64
curl -L -o mcp-telegram-login https://github.com/mcp-telegram/mcp-telegram/releases/latest/download/mcp-telegram-login-linux-x64
chmod +x mcp-telegram mcp-telegram-login

# Login
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH ./mcp-telegram-login

# Run
./mcp-telegram

From source

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

Docker

docker build -t mcp-telegram https://github.com/mcp-telegram/mcp-telegram.git

Login (interactive terminal required):

docker run -it --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  --entrypoint node mcp-telegram dist/qr-login-cli.js

Run the MCP server:

docker run -i --rm \
  -e TELEGRAM_API_ID=YOUR_ID \
  -e TELEGRAM_API_HASH=YOUR_HASH \
  -v ~/.mcp-telegram:/root/.mcp-telegram \
  mcp-telegram

Note: Login must be done once via terminal. After that, the session is persisted in ~/.mcp-telegram and reused automatically.

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"
      }
    }
  }
}

  1. Restart Claude Desktop.

  2. Ask Claude: "Run telegram-login" -- a QR code will appear. If the image is not visible, it's also saved to ~/.mcp-telegram/qr-login.png. Scan it in Telegram (Settings > Devices > Link Desktop Device).

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

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

Claude Desktop (Binary)

Same setup, but using the pre-built binary instead of npx:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "env": {
        "TELEGRAM_API_ID": "YOUR_ID",
        "TELEGRAM_API_HASH": "YOUR_HASH"
      }
    }
  }
}

Claude Desktop (Docker)

  1. Login via terminal first (see Docker section above).

  2. Add to your config file:

{
  "mcpServers": {
    "telegram": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TELEGRAM_API_ID=YOUR_ID",
        "-e", "TELEGRAM_API_HASH=YOUR_HASH",
        "-v", "~/.mcp-telegram:/root/.mcp-telegram",
        "mcp-telegram"
      ]
    }
  }
}
  1. Restart Claude Desktop. Ask Claude: "Run telegram-status" to verify.

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!,
      },
    },
  },
});

Tools

All tools are auto-discoverable via MCP — your AI client will see the full list with parameters and descriptions when connected.

Category Tools
Auth telegram-status, telegram-login, telegram-logout
Messaging telegram-send-message, telegram-edit-message, telegram-delete-message, telegram-forward-message, telegram-send-scheduled, telegram-send-typing, telegram-translate-message, telegram-get-message-link
Scheduled telegram-get-scheduled, telegram-delete-scheduled
Reading telegram-list-chats, telegram-read-messages, telegram-search-messages, telegram-search-global, telegram-search-chats, telegram-get-unread, telegram-mark-as-read, telegram-get-replies, telegram-get-unread-mentions, telegram-get-unread-reactions, telegram-get-saved-dialogs
Drafts telegram-save-draft, telegram-get-drafts, telegram-clear-drafts
Forum Topics telegram-list-topics, telegram-read-topic-messages, telegram-create-topic, telegram-edit-topic, telegram-delete-topic
Polls telegram-create-poll
Reactions telegram-send-reaction, telegram-get-reactions, telegram-set-default-reaction, telegram-get-top-reactions, telegram-get-recent-reactions
Stickers telegram-send-sticker, telegram-get-installed-stickers, telegram-get-recent-stickers, telegram-get-sticker-set, telegram-search-sticker-sets
Media telegram-send-file, telegram-download-media, telegram-get-profile-photo, telegram-get-web-preview
Groups telegram-create-group, telegram-edit-group, telegram-invite-to-group, telegram-join-chat, telegram-leave-group, telegram-kick-user, telegram-ban-user, telegram-unban-user, telegram-set-admin, telegram-remove-admin, telegram-get-my-role, telegram-set-chat-permissions, telegram-set-slow-mode, telegram-get-admin-log
Chat Info telegram-get-chat-info, telegram-get-chat-members, telegram-get-chat-folders
Invite Links telegram-create-invite-link, telegram-get-invite-links, telegram-revoke-invite-link
Contacts telegram-get-contacts, telegram-add-contact, telegram-get-contact-requests
Moderation telegram-block-user, telegram-unblock-user, telegram-report-spam
Profiles telegram-get-profile, telegram-update-profile
Account telegram-get-sessions, telegram-terminate-session, telegram-set-privacy, telegram-set-auto-delete
Pinning telegram-pin-message, telegram-unpin-message
Chat Settings telegram-mute-chat, telegram-archive-chat, telegram-pin-chat, telegram-mark-dialog-unread
Admin Toggles telegram-toggle-channel-signatures, telegram-toggle-anti-spam, telegram-toggle-forum-mode, telegram-toggle-prehistory-hidden, telegram-set-chat-reactions, telegram-approve-join-request
Stats telegram-get-broadcast-stats, telegram-get-megagroup-stats
Inline Bots & Buttons telegram-inline-query, telegram-inline-query-send, telegram-press-button, telegram-get-message-buttons
Real-Time Polling telegram-get-state, telegram-get-updates, telegram-get-channel-updates
Stories telegram-get-all-stories, telegram-get-peer-stories, telegram-get-stories-by-id, telegram-get-story-views
Boosts & Business telegram-get-my-boosts, telegram-get-boosts-status, telegram-get-boosts-list, telegram-get-business-chat-links
Opt-in (env-gated) telegram-get-group-call, telegram-get-group-call-participants (requires MCP_TELEGRAM_ENABLE_GROUP_CALLS=1), telegram-get-stars-status, telegram-get-stars-transactions (requires MCP_TELEGRAM_ENABLE_STARS=1), telegram-get-quick-replies, telegram-get-quick-reply-messages (requires MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1)

Tip: Ask your AI assistant "What Telegram tools are available?" to get the full list with parameters and descriptions.

Optional Features

Some tools are disabled by default and must be opted in via environment variables:

Variable Value Tools enabled
MCP_TELEGRAM_ENABLE_GROUP_CALLS 1 telegram-get-group-call, telegram-get-group-call-participants
MCP_TELEGRAM_ENABLE_STARS 1 telegram-get-stars-status, telegram-get-stars-transactions
MCP_TELEGRAM_ENABLE_QUICK_REPLIES 1 telegram-get-quick-replies, telegram-get-quick-reply-messages

Add these to your .env file or MCP client config to enable them.

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
  telegram-client.ts  -- TelegramService class (GramJS wrapper)
  qr-login-cli.ts     -- CLI utility for QR code login
  tools/              -- Modular tool definitions
    auth.ts           -- Connection & login
    messages.ts       -- Send, read, search, edit, delete, forward; inline bots; real-time polling
    chats.ts          -- Chat listing, group management, admin toggles, stats
    contacts.ts       -- Contacts, profiles, moderation
    media.ts          -- Files, photos, downloads
    reactions.ts      -- Reactions, set-chat-reactions
    extras.ts         -- Pin, schedule, polls, topics
    stickers.ts       -- Sticker sets, send, search, browse
    account.ts        -- Sessions, privacy, auto-delete, profile, chat mute/folders, invite links, business chat links
    boosts.ts         -- Boost status, my boosts, boosters list
    stories.ts        -- Stories: list all, peer, by-id, view stats
    group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)
    stars.ts          -- Stars wallet status and transactions (opt-in: MCP_TELEGRAM_ENABLE_STARS)
    quick-replies.ts  -- Quick replies and messages (opt-in: MCP_TELEGRAM_ENABLE_QUICK_REPLIES)
    shared.ts         -- Shared utilities

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

Troubleshooting

AUTH_KEY_DUPLICATED

A Telegram session can only be used by one process at a time. If you get AUTH_KEY_DUPLICATED, it means another process is already using the same session file.

Solution: Create separate sessions for each environment:

# Local development
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-local npx @overpod/mcp-telegram login

# Production server
TELEGRAM_SESSION_PATH=~/.mcp-telegram/session-prod npx @overpod/mcp-telegram login

Then set TELEGRAM_SESSION_PATH in each environment's MCP config accordingly.

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
  • No data is sent to third-party services -- all communication goes directly to Telegram servers via MTProto
  • QR login codes are generated locally and never leave your machine
  • One session per process -- using the same session in multiple processes simultaneously causes AUTH_KEY_DUPLICATED errors (see Troubleshooting)
  • This is a userbot (personal account), not a bot -- respect the Telegram Terms of Service

License

MIT

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选