# overpod/mcp-telegram [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/overpod/mcp-telegram  
**GitHub Stars:** 41  
**npm Downloads (last month):** 3456  
**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": ""
    }
  }
}
```

**Requires environment variables:** `TELEGRAM_API_ID`, `TELEGRAM_API_HASH` — 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 MCP server does

The overpod/mcp-telegram MCP server exposes a Telegram user account to AI assistants through the Model Context Protocol. It uses Telegram's MTProto interface through GramJS, so the connection runs with the permissions and visibility of the authenticated personal account rather than a bot account.

The server is intended for clients that need to inspect or act on Telegram data. Supported areas include chat and message access, global message search, media downloads, contacts, reactions, polls, scheduled messages, stickers, stories, forum topics, inline bots, callback buttons, and read receipts. It also includes account and profile operations, privacy settings, chat folders, channel and group administration, analytics, business features, and optional Stars and gifts functionality.

## How it works

A local process communicates with an MCP client over the standard local server arrangement. The process connects to Telegram using an API ID and API hash obtained from Telegram's API development tools. On first login, it displays a QR code; scanning that code from Telegram's device-linking screen authorizes the account. The resulting session is stored locally and reused after restarts.

The overpod/mcp-telegram MCP server can also poll for updates using stateless cursors. The agent maintains the Telegram update state values, including `pts`, `qts`, and `date`. For several clients using one account, a shared daemon can own the Telegram connection and proxy calls over a local Unix socket, avoiding concurrent-session conflicts.

## Setup and configuration

Node.js 18 or newer is required. Install or run the package with `npx @overpod/mcp-telegram`, supplying `TELEGRAM_API_ID` and `TELEGRAM_API_HASH`. Run the package's `login` command first to complete QR authentication. If the account uses Telegram cloud-password two-factor authentication, set `TELEGRAM_2FA_PASSWORD` during login; the password is used for the authentication challenge and is not saved.

`TELEGRAM_SESSION_PATH` changes where the session file is stored and allows separate accounts to run side by side. Proxy variables support SOCKS4, SOCKS5, or MTProxy connections, including `TELEGRAM_PROXY_IP`, `TELEGRAM_PROXY_PORT`, and `TELEGRAM_PROXY_SECRET`. `TELEGRAM_USE_WSS=true` selects WSS connectivity. The optional Stars tools require `MCP_TELEGRAM_ENABLE_STARS=1`.

## Tools and capabilities

The overpod/mcp-telegram MCP server supports capabilities for:

- Reading chats and messages, searching globally, and retrieving updates.
- Sending messages, reactions, polls, scheduled messages, stickers, and media.
- Listing forum topics, reading topic messages, and sending to a selected topic.
- Managing contacts, profiles, privacy controls, sessions, folders, and auto-delete settings.
- Reading and managing stories, discussion groups, join requests, channel settings, and group statistics.
- Working with inline bots, callback buttons, Telegram Business features, boosts, and optional Stars features.

## Limitations and notes

This integration operates as a personal Telegram account, so actions and data access are tied to that account. It requires Telegram API credentials from `my.telegram.org`; the QR code is an authentication method, not a replacement for those credentials. Multiple processes opening the same account session can conflict, so the shared-daemon mode is intended for concurrent clients.

The server requires local session storage unless a custom path is configured. Proxy settings may be needed when Telegram connectivity is restricted. The README also lists a hosted version, but the local setup described here runs the npm package directly. The project is licensed under MIT.

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