Log inSubmit server
MCP Telegram logo

MCP Telegram

by overpod

Connects AI assistants to a personal Telegram account for chat search, media downloads, contacts, messaging, and account management.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install 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": {
    "overpod-mcp-telegram": {
      "command": "npx",
      "args": [
        "-y",
        "@overpod/mcp-telegram"
      ],
      "env": {
        "TELEGRAM_API_ID": "YOUR_VALUE_HERE",
        "TELEGRAM_API_HASH": "YOUR_VALUE_HERE",
        "TELEGRAM_SESSION_PATH": "YOUR_VALUE_HERE",
        "TELEGRAM_2FA_PASSWORD": "YOUR_VALUE_HERE",
        "TELEGRAM_PROXY_IP": "YOUR_VALUE_HERE",
        "TELEGRAM_PROXY_PORT": "YOUR_VALUE_HERE",
        "TELEGRAM_PROXY_SOCKS_TYPE": "YOUR_VALUE_HERE",
        "TELEGRAM_PROXY_SECRET": "YOUR_VALUE_HERE"
      }
    }
  }
}

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

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

overpod/mcp-telegram connects MCP-compatible AI clients to Telegram through MTProto and GramJS, operating as a userbot under a personal account rather than through the Bot API. Its tools cover chat and message access, global search, media downloads, contacts, reactions, polls, stickers, stories, account settings, and administrative operations. QR login saves a reusable session, while a shared daemon can let multiple clients use one Telegram connection. Reach for it when an agent needs access to personal Telegram chats, history, media, or account-level features.

Use cases

  • Search messages across Telegram chats
  • Summarize conversations and forum topics
  • Download media from messages
  • Manage contacts and account settings
  • Operate multiple MCP clients through one Telegram session

Key features

  • MTProto access through GramJS
  • QR-code login with persistent sessions
  • Global message search and media downloads
  • Messaging, reactions, polls, stickers, and stories
  • Account, contact, privacy, and chat-folder management
  • Shared daemon for concurrent MCP clients

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.

20/21 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

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

Adoption & maintenance

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

GitHub stars60Stargazers on the source repository.
npm downloads4.7kPackage downloads in the last 30 days.
Last commit2d agoMost recent push to the default branch.
Directory activity3 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Telegram works

What overpod/mcp-telegram does

overpod/mcp-telegram exposes Telegram operations through the Model Context Protocol. It connects to Telegram using MTProto through GramJS and acts as a userbot, so actions run under the authenticated personal account rather than a separate bot identity. The server is suited to assistants that need to read conversations, search message history, inspect contacts, download media, or perform account and chat operations.

Its coverage extends beyond basic messaging. Available capabilities include reactions, polls, scheduled messages, stickers, forum topics, inline bots and callback buttons, stories, discussion groups, read receipts, channel and supergroup statistics, admin controls, boosts, Telegram Business settings, chat folders, privacy settings, and account profile management. Star and gift operations can be enabled separately.

How it works

The server communicates with Telegram over MTProto and exposes the resulting operations as MCP tools. Login is performed with a QR code: scan it from Telegram's Settings > Devices > Link Desktop Device, then the resulting session is reused after restarts. The session is stored at ~/.mcp-telegram/session by default and can be relocated with TELEGRAM_SESSION_PATH.

A single account can be used by multiple MCP clients through the shared-daemon mode. The daemon owns the Telegram connection, while client processes proxy calls over a local Unix socket. This avoids concurrent processes evicting one another from the same Telegram session. Separate accounts can instead run side by side by using different session paths.

Real-time polling uses stateless cursors; the agent maintains the {pts, qts, date} state returned for subsequent polling. Output resolves sender names instead of exposing only numeric identifiers.

Setup and configuration

Node.js 18 or later is required. Create Telegram API credentials at my.telegram.org, then log in with:

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

Add the package as an MCP server after login. For Claude Code, for example:

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

Accounts protected by Telegram cloud-password verification also need TELEGRAM_2FA_PASSWORD during login. The password is used locally for the authentication challenge and is not persisted. Set TELEGRAM_SESSION_PATH for a custom or per-account session file.

Network configuration supports SOCKS4/SOCKS5 and MTProxy through the proxy environment variables, including TELEGRAM_PROXY_IP, TELEGRAM_PROXY_PORT, TELEGRAM_PROXY_SECRET, and optional proxy credentials. TELEGRAM_USE_WSS=true enables WSS connections when outbound port 443 is needed. To share one account across several clients, start mcp-telegram serve with the Telegram credentials and point each client at the same installation and session path.

Tools and capabilities

The tool set supports the following work:

  • Read chats, messages, forum topics, stories, read receipts, and account data.
  • Search messages globally or within Telegram content and download media.
  • Send messages, reactions, polls, scheduled messages, stickers, inline-bot results, and callback-button interactions.
  • Manage contacts, profiles, privacy settings, sessions, chat folders, auto-delete timers, and business settings.
  • Administer supported channel and group settings, approve join requests, and retrieve channel or supergroup statistics.
  • Inspect discussion groups, boosts, gifts, Stars, and subscriptions; Star features require MCP_TELEGRAM_ENABLE_STARS=1.

Limitations and notes

This integration uses a personal Telegram account, so its access model differs from a Bot API integration. Telegram API credentials are required for the local server, even though QR code handles the account login. A cloud password requires the additional 2FA environment variable during login.

Multiple processes should not independently open the same Telegram session. Use the shared daemon for concurrent clients, or assign distinct session paths to separate accounts. Proxy settings may be needed when Telegram connectivity is restricted or when running in containerized environments.

The package is released under the MIT license.

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 MCP Telegram

overpod/mcp-telegram is an MCP server that connects AI assistants to Telegram through MTProto and GramJS using a personal user account. Its main tools read chats, search messages, download media, manage contacts, send messages, handle stickers and stories, and update supported account, chat, and administrative settings.

Install and run it with `npx @overpod/mcp-telegram` after obtaining Telegram API credentials. First run the `login` command with `TELEGRAM_API_ID` and `TELEGRAM_API_HASH`, scan the displayed QR code, then register the package in your MCP client.

Log in by running `TELEGRAM_API_ID=YOUR_ID TELEGRAM_API_HASH=YOUR_HASH npx @overpod/mcp-telegram login` and scanning the terminal QR code from Telegram's Settings > Devices > Link Desktop Device. Add `TELEGRAM_2FA_PASSWORD` during login when the account uses a cloud password.

Yes. Start `mcp-telegram serve` as a shared daemon so one process owns the Telegram connection, then point other clients to the same installation and session path. The clients proxy calls through a local Unix socket instead of opening competing connections.

Yes. Cursor is named as a supported MCP client, and the server can be launched with its standard `npx @overpod/mcp-telegram` command and the required Telegram environment variables.

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 PreviewMCP Telegram AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/overpod-mcp-telegram?style=directory)](https://allmcps.com/mcp/overpod-mcp-telegram)
HTML Embed
<a href="https://allmcps.com/mcp/overpod-mcp-telegram"><img src="https://allmcps.com/api/badge/overpod-mcp-telegram?style=directory" alt="MCP Telegram on AllMCPs" /></a>