# overpod/mcp-telegram [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/overpod/mcp-telegram  
**GitHub Stars:** 60  
**npm Downloads (last month):** 4736  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/overpod-mcp-telegram

## Description
Telegram MCP server via MTProto/GramJS — 20 tools for reading chats, searching messages, downloading media, managing contacts. QR code login, npx zero-install. Hosted version at mcp-telegram.com.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-telegram": {
    "command": "npx",
    "args": ["-y","@overpod/mcp-telegram"],
    "env": {
      "TELEGRAM_API_ID": "",
      "TELEGRAM_API_HASH": "",
      "TELEGRAM_SESSION_PATH": "",
      "TELEGRAM_2FA_PASSWORD": "",
      "TELEGRAM_PROXY_IP": "",
      "TELEGRAM_PROXY_PORT": "",
      "TELEGRAM_PROXY_SOCKS_TYPE": "",
      "TELEGRAM_PROXY_SECRET": ""
    }
  }
}
```

**Requires environment variables:** `TELEGRAM_API_ID`, `TELEGRAM_API_HASH`, `TELEGRAM_SESSION_PATH`, `TELEGRAM_2FA_PASSWORD`, `TELEGRAM_PROXY_IP`, `TELEGRAM_PROXY_PORT`, `TELEGRAM_PROXY_SOCKS_TYPE`, `TELEGRAM_PROXY_SECRET` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

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

```bash
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.

_Full upstream README: https://allmcps.com/mcp/overpod-mcp-telegram/readme_