Telegram (mcp Telegram)

MCP server for Telegram userbot — messages, media, reactions, polls & more. Built on GramJS/MTProto.

Communication
56stars
No ratings
UpdatedOct 21, 2026

InstallRepository Website

Install Telegram (mcp Telegram)

Pick your client, then add it in one click or paste the config.

STDIONode.js

~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "telegram-mcp-telegram": {
      "command": "npx",
      "args": [
        "-y",
        "@overpod/mcp-telegram"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y @overpod/mcp-telegram

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked Today.

Overview

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

8/8 checks healthy over the last 42d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · @overpod/mcp-telegram (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars56Stargazers on the source repository.

npm downloads4.1kPackage downloads in the last 30 days.

Last commit3d agoMost recent push to the default branch.

Install checkInconclusiveDidn't respond in our test window — often a slow first install.

From the project README

Telegram MCP Server

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

Telegram MCP Server — a Model Context Protocol server that connects AI assistants like Claude and ChatGPT 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
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 & profile management -- update profile, set emoji status, birthday, personal channel, profile photo, manage privacy settings, sessions, auto-delete timers
Chat folders -- create, edit, delete and reorder folders, toggle folder tags, read suggested folders (v1.33.0)
Global privacy -- read and set account-wide privacy settings (v1.33.0)
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; publish/edit/delete stories, react, pin, stealth mode, archive, report (v1.30.0)
Discussion -- get discussion-group info for channel posts with comments, list groups eligible for discussion (v1.30.0)
Read Receipts -- who read a message in a small group, when your private message was read (v1.30.0)
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 CRUD, work hours, location, greeting/away/intro messages
Star gifts -- browse available and saved gifts, save/convert gifts, manage Stars balance and subscriptions (opt-in via MCP_TELEGRAM_ENABLE_STARS=1, v1.34.0)
Shared daemon -- one background process serves multiple MCP clients over a single Telegram session; see the shared-daemon guide (v1.38.0)
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

bash

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.

Two-step verification (2FA): if your account has a cloud password enabled, scanning the QR code is not enough — Telegram also requires the password. Provide it via TELEGRAM_2FA_PASSWORD so the login can complete:
bash
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH TELEGRAM_2FA_PASSWORD=YOUR_PASSWORD npx @overpod/mcp-telegram login
The password is only used locally to answer Telegram's SRP challenge and is never persisted.

3. Add to Claude

Terminal

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:

bash

# 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:

Terminal

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.

Multiple agents / concurrent clients (shared daemon)

The opposite of multiple accounts: one account driven by many clients at once — several Claude Code windows, parallel sub-agents, or multiple IDEs. Normally each process opens the same session and they evict one another with AUTH_KEY_DUPLICATED. Serve mode fixes this.

Run a single persistent daemon that owns the one Telegram connection. Every other process auto-detects the daemon (via a PID lock) and becomes a thin client that proxies tool calls to it over a local Unix socket:

bash

# On the host, once: start the daemon (owns the connection, no stdio)
TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH mcp-telegram serve
# (or set MCP_TELEGRAM_DAEMON=1 instead of the `serve` argument)

Then point each MCP client at the same install with the same TELEGRAM_SESSION_PATH — no serve argument. They connect to the daemon automatically; closing any client never drops the shared connection. Credentials are only required by the daemon (the owner), so client commands can omit TELEGRAM_API_ID/TELEGRAM_API_HASH and keep them where the daemon runs.

See the shared daemon guide for a systemd unit and SSH usage.

Proxy Support

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

bash

# 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

Connecting via WSS (port 443)

If your VPS or hosting IP is reachable on outbound port 443 but not the default MTProto port 80 (some cloud providers ban port 80 on Telegram DC IP ranges as anti-abuse policy), set:

bash

TELEGRAM_USE_WSS=true npx @overpod/mcp-telegram

Variable	Description
`TELEGRAM_USE_WSS`	When `true`, gramJS uses port `443` instead of `80` for the MTProto TCPFull transport. Default: `false`. Cannot be combined with `TELEGRAM_PROXY_*` (gramJS limitation) — if both are set, `useWSS` is ignored and the proxy takes precedence (a warning is logged).

Installation Options

npx (recommended, zero install)

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

Global install

Terminal

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:

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Telegram (mcp Telegram)

Telegram (mcp-telegram) is an MCP server that connects AI assistants such as Claude and ChatGPT to Telegram through MTProto. It runs as a userbot under your personal Telegram account, using GramJS, and supports messaging, media, reactions, polls, scheduled messages, stickers, contacts, message history, forum topics, stories, and more.

mcp-telegram uses a personal Telegram account as a userbot rather than the limited Bot API. It connects through the MTProto protocol and can access the account’s chats, contacts, and message history.

The Telegram MCP server supports messaging, media, reactions, polls, scheduled messages, stickers, contacts, forum topics, global message search, stories, inline bots, buttons, read receipts, administrative controls, analytics, and account or profile management.

mcp-telegram supports QR code login through the Telegram app and persists the session so you can stay connected across restarts. The cloud version advertises QR-code connection without API keys.

Related MCP servers

All in Communication All alternatives

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Telegram (mcp Telegram) AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/telegram-mcp-telegram?style=directory)](https://allmcps.com/mcp/telegram-mcp-telegram)

HTML Embed

<a href="https://allmcps.com/mcp/telegram-mcp-telegram"><img src="https://allmcps.com/api/badge/telegram-mcp-telegram?style=directory" alt="Telegram (mcp Telegram) on AllMCPs" /></a>

At a glance

Category: Communication
Transport: STDIO
Runtime: Node.js
Last updated: Oct 21, 2026

GitHub stars56

Last commit3d ago

npm / month4,095

49Quality signal: Fair · 49/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools16/30

Adoption & activity11/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

Own this project?

This listing is pre-filled from public sources. Claim it via your GitHub README, a site badge, or DNS TXT to edit it and earn the Verified badge.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically.

Claim this listing

Install Telegram (mcp Telegram)

Supply-chain signal

Adoption & maintenance

From the project README

Telegram MCP Server

Features

Prerequisites

Quick Start

1. Get Telegram API credentials

2. Login

3. Add to Claude

Multiple Accounts

Multiple agents / concurrent clients (shared daemon)

Proxy Support

Connecting via WSS (port 443)

Installation Options

npx (recommended, zero install)

Global install

Pre-built binary (no runtime needed)

Frequently Asked Questions about Telegram (mcp Telegram)

What is the Telegram (mcp-telegram) MCP server?

Does mcp-telegram use a Telegram bot or a personal account?

What can the Telegram MCP server do?

How do I authenticate mcp-telegram with Telegram?

AllMCPs Directory Badge