Telegram MCP Server
Community MCP server for Telegram - connects AI agents to a personal Telegram account via MTProto, 181 tools for messages, media, and more.
- Skill Road
- Telegram MCP Server
Categories
Description
Telegram MCP Server is a community project maintained by overpod that makes Telegram accessible to AI agents such as Claude or ChatGPT via the Model Context Protocol. It is not an official Telegram product; Telegram itself is not involved in its development or operation. The official product page is https://mcp-telegram.com, and the repository https://github.com/mcp-telegram/mcp-telegram contains source code, license, and README. Per the provider, it is the most feature-complete Telegram MCP server available, with 181 tools.
MTProto instead of the Bot API
Unlike many Telegram integrations, the server does not use the limited Bot API but the broader MTProto protocol via the GramJS library. That means it runs as a so-called userbot, acting on behalf of the personal Telegram account of whoever sets it up - not as a separate bot account, and not on behalf of Skill Road or any third party. As a result, an agent generally gains access to the same scope of chats, contacts, and message history that the account owner sees in the Telegram app.
Feature scope
Per the README, the server covers messages, media, reactions, polls, scheduled messages, stickers, contact and profile management, forum topics, chat folders, global search across all chats, inline bots and buttons, stories, read-receipt status, admin functions for channels and groups, and channel/group statistics. According to the provider, a shared background daemon can serve multiple MCP clients from a single Telegram session.
Setup: self-host or cloud version
For self-hosting, the server is started via npx and requires your own Telegram API credentials (API_ID and API_HASH) from my.telegram.org, plus a one-time QR-code login whose session is then stored locally. Alternatively, the provider offers a hosted cloud version at mcp-telegram.com, described as requiring no personal API keys and being ready via QR-code login in a short time. Skill Road only lists this catalog entry with links to both official routes; installation happens exclusively through the linked provider sources.
Permissions, data access, and security boundaries
Because the server runs as a userbot with the full account access of whoever sets it up, the intended scope should be clearly defined in advance. A compromised session token could potentially allow reading and writing across every chat, contact, and channel visible to that account. Credentials and session files belong only in secure, local storage or environment variables, never in prompts, commits, or publicly accessible configuration files. For sensitive business-related features such as Stars balances, the README requires a separate opt-in via environment variable, which helps prevent accidental activation.
License, GitHub stars, and fit
The repository is MIT licensed. The GitHub API reported exactly 42 stars on 2026-09-07; that number is a snapshot of repository popularity, not evidence of security, quality, or long-term maintenance. The server itself is open source and free to use; the cloud version's specific terms may vary by provider plan, so this public entry does not state fixed prices. Messaging & Communication is the right category because the server makes chat content, contacts, and messaging actions accessible to agents.
A sensible first test is a secondary account or a narrowly scoped use case, such as summarizing a single channel, before granting full account access for production automation.
Requirements
Node.js 18 or newer, a personal Telegram account, and either Telegram API credentials (API_ID/API_HASH) for self-hosting or an account on the hosted cloud version.
Installation instructions
Quick start
For self-hosting, run npx @overpod/mcp-telegram login with your own API_ID/API_HASH and sign in via QR code, or alternatively use the hosted cloud version at mcp-telegram.com.
npx @overpod/mcp-telegram login
Classification and the main warning
Telegram MCP Server is a community project by overpod and not an official Telegram product. According to the provider, it connects AI clients to a Telegram account through the Model Context Protocol. MCP is a standard that lets an agent call structured tools. In this case, the tools cover chats, messages, media, contacts, and other Telegram functions. The key point for beginners is that the server is not a harmless search index; depending on configuration, it can access real Telegram data through the connected account.
According to the README, the project uses MTProto through GramJS and operates as a userbot. A userbot is not a separate bot account with limited Bot API access. It acts on behalf of the personal account that signed in. As a result, access can be much broader than in many classic bot integrations. That is why it should not be casually tested with a primary account. The intended use should be planned, limited, and documented.
Choose self-hosting or cloud
The provider describes two paths: self-hosting and a hosted cloud version. With self-hosting, the package runs in your own environment. You need a Telegram account and Telegram API credentials from my.telegram.org. These usually include an API ID and API hash. They are not public information and do not belong in prompts, screenshots, commits, or shared configuration files. Login happens through a QR code or similar flow, after which a session is stored.
The cloud version is described by the provider as avoiding personal API keys and being quicker to start through a QR code. That can be convenient, but it moves more trust and operation to the provider. Before choosing, teams should decide which data will be processed, whether internal policy allows a cloud connection, who can access the session, and how access can be revoked. For sensitive organizations, self-hosting may be easier to control, but only if operations, updates, and secret handling are reliable.
Understand the access scope
The README lists many tools, including messages, media, reactions, polls, scheduled messages, stickers, contacts, profiles, forum topics, chat folders, global search, inline bots, stories, read status, admin functions, and statistics. That breadth is useful, but it increases risk. Depending on the tool, an agent may not only read but also prepare or perform actions. A narrow first use case is wise, such as summarizing one channel or searching harmless chats.
Before production use, define which chats and actions are allowed. If the account can see private groups, customer conversations, or internal channels, that content may enter model context. The server is only one part of the chain. The AI client and model provider also determine how returned data is processed. Reducing account and chat access is therefore one of the strongest safeguards.
Step 1: Setup, sessions, and operational safety
For self-hosting, the runtime environment should be current and meet the officially stated prerequisites. Credentials belong in environment variables or a secure secret mechanism. Session files are especially sensitive because they may allow future access without repeating the login. They should be local, protected, and kept out of project folders that are synced, published, or freely readable by agents.
After login, run a harmless read-only test. Check which chats are visible, what data the agent returns, and whether unexpected write tools are available. Do not enable sensitive functions simply because they exist. If the project offers options for especially delicate areas, keep them disabled until there is a clear need and approval. Apply updates regularly after reviewing changelog and compatibility.
Limits and best practices
Telegram MCP Server can be useful for searching messages, summarizing channels, managing media, or bringing communication workflows into agents. It is most valuable when a team has clear, repeatable information tasks. Even so, it remains a community project without official Telegram involvement. That does not automatically make it unsafe, but it requires more self-review of provenance, code, license, release state, and privacy impact.
The most important practices are straightforward: do not start with your most important personal account, use a separate account or narrow test area when possible, protect sessions, limit write actions, and write prompts so the agent does not send unwanted messages. If the use case is business-critical or legally sensitive, clarify privacy, retention, access rights, and revocation before starting. Treat the server as a powerful account bridge, not as a simple chat add-on.
npx @overpod/mcp-telegram login
Authentication
QR-code login with your own Telegram account; self-hosting additionally requires API_ID and API_HASH from my.telegram.org, with the session stored locally.
Required access permissions
The server acts as a userbot with the full access scope of the connected personal Telegram account, including chats, contacts, and message history.
Transmitted or stored data
Tool calls access Telegram chats, media, and account data of the connected account via MTProto and return results to the MCP client.
Security risks
As a community project unaffiliated with Telegram, a compromised session lets the server act with the account owner’s full access scope; session files and API credentials belong only in secure, local storage.
License and costs
- License
- MIT
- Cost
- free
The server is MIT licensed and free for self-hosting. The hosted cloud version follows the provider’s own terms.
Alternatives
Not recorded yet.
At a glance
- Provider
- overpod
- Status
- Community
- Deployment
- Local and remote
- Current version
- Not recorded yet.
- GitHub stars
- 71
- Last reviewed
- 07.09.2026
Repository and documentation
Categories
Supported clients
Related guides
Guides and background related to this entry.
No related guides yet.