MCP Telegram

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.