MCP Telegram
Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw MTProto
What is MCP Telegram?
MCP Telegram is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to telegram mcp server (mtproto). connect claude, cursor, claude code, vs code, codex, cline, windsurf to a real telegram account — read/search/send messages, moderate channels, manage stories/contacts/f...
Telegram MCP server (MTProto). Connect Claude, Cursor, Claude Code, VS Code, Codex, Cline, Windsurf to a real Telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw MTProto
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Telegram MCP server (MTProto). Connect Claude, Cursor, Claud
Use Cases
Maintainer
Works with
Installation
NPM
npx -y mcp-telegramManual Installation
npx -y mcp-telegramConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use MCP Telegram
MCP Telegram is a Python-based MCP server that connects AI assistants to a real Telegram user account using the MTProto protocol via the Telethon library. Unlike bot-based integrations, it authenticates as a full Telegram user and exposes tools to send, edit, and delete messages, search chats and channels, retrieve message history, manage drafts, and download media attachments. Developers and power users who want Claude or another AI assistant to read and respond to their actual Telegram conversations — not just a bot account — will find this server the most capable Telegram integration available for MCP-compatible clients.
Prerequisites
- Python 3.10 or newer
- uv package manager installed (https://docs.astral.sh/uv/)
- A Telegram account with a real phone number
- Telegram API credentials: API_ID and API_HASH obtained from https://my.telegram.org/apps
- An MCP client such as Claude Desktop, Cursor, or VS Code with MCP extension
Obtain Telegram API credentials
Log in to https://my.telegram.org/apps with your Telegram phone number. Create a new application to receive your API_ID (a number) and API_HASH (a hex string). Keep these private — they identify your application to Telegram.
Install mcp-telegram using uv
Install the mcp-telegram package as a uv tool so the 'mcp-telegram' command is available globally.
uv tool install mcp-telegramAuthenticate with your Telegram account
Run the login command and provide your API credentials and phone number when prompted. Telegram will send a verification code to your account; enter it to complete authentication. If you have two-factor authentication enabled, you will also be asked for your 2FA password.
mcp-telegram loginAdd MCP Telegram to your MCP client configuration
Add the server to your Claude Desktop config file. The API_ID and API_HASH must be set in the env block.
{
"mcpServers": {
"mcp-telegram": {
"command": "mcp-telegram",
"args": ["start"],
"env": {
"API_ID": "12345678",
"API_HASH": "your_api_hash_here"
}
}
}
}Restart your MCP client and start messaging
Restart Claude Desktop to pick up the new server. The server authenticates using the session saved during 'mcp-telegram login', so no further authentication steps are needed. You can now ask Claude to interact with your Telegram account.
MCP Telegram Examples
Client configuration
Complete claude_desktop_config.json for MCP Telegram. Replace the API_ID and API_HASH values with your own from my.telegram.org.
{
"mcpServers": {
"mcp-telegram": {
"command": "mcp-telegram",
"args": ["start"],
"env": {
"API_ID": "12345678",
"API_HASH": "abcdef1234567890abcdef1234567890"
}
}
}
}Prompts to try
Example prompts for interacting with your Telegram account through Claude.
- "Show me the last 10 messages in my 'Family' group chat."
- "Send a message to @username saying 'I'll be 10 minutes late'."
- "Search my Telegram chats for conversations mentioning 'project deadline'."
- "Download the video that was sent in the 'Design Team' channel today."
- "Check my message drafts and tell me what I have pending to send."
- "Find the Telegram channel named 'Tech News' and show me today's top posts."Troubleshooting MCP Telegram
'mcp-telegram' command not found after uv tool install
Run 'uv tool update-shell' to add uv's tool bin directory to your PATH, then open a new terminal. Verify with 'uv tool list | grep mcp-telegram'. You can also invoke it directly via 'uvx mcp-telegram start'.
Login fails with 'PhoneNumberInvalidError' or 'ApiIdInvalidError'
Double-check your API_ID (must be an integer, no quotes) and API_HASH (32-character hex string) from my.telegram.org. The phone number must include the country code in international format (e.g., +1234567890). If you recently created the API app, wait a few minutes before trying again.
Session expires and authentication is required again
MTProto sessions can expire if Telegram revokes them (e.g., after a password change or suspicious login). Re-run 'mcp-telegram login' to create a fresh session. The session file is stored locally; deleting it forces a full re-authentication.
Frequently Asked Questions about MCP Telegram
What is MCP Telegram?
MCP Telegram is a Model Context Protocol (MCP) server that telegram mcp server (mtproto). connect claude, cursor, claude code, vs code, codex, cline, windsurf to a real telegram account — read/search/send messages, moderate channels, manage stories/contacts/folders, transcribe voice, and call any raw mtproto It connects AI assistants to external tools and data sources through a standardized interface.
How do I install MCP Telegram?
Install via npm with the command: npx -y mcp-telegram. Then add the server configuration to your AI client's JSON config file (e.g., claude_desktop_config.json or .cursor/mcp.json).
Which AI clients work with MCP Telegram?
MCP Telegram works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is MCP Telegram free to use?
Yes, MCP Telegram is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
MCP Telegram Alternatives — Similar Communication Servers
Looking for alternatives to MCP Telegram? Here are other popular communication servers you can use with Claude, Cursor, and VS Code.
Slack
★ 86.1kEnables interaction with Slack workspaces through comprehensive channel management, messaging, user management, file uploads, and Block Kit formatting. Features secure credential storage via macOS Keychain and supports all major Slack operations incl
LibreChat
★ 37.3kEnhanced ChatGPT Clone: Features Agents, MCP, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenA
Note Gen
★ 11.9kA cross-platform Markdown AI note-taking software.
DeepChat
★ 5.8k🐬DeepChat - A smart assistant that connects powerful AI to your personal world
WhatsApp MCP
★ 5.7kConnects AI assistants to the official Meta WhatsApp Cloud API for managing conversations and sending various message types through natural language. It provides tools for media management, template messages, and real-time webhook processing without
Apple
★ 3.1kEnables interaction with Apple apps like Messages, Notes, and Contacts through the MCP protocol to send messages, search, and open app content using natural language.
Browse More Communication MCP Servers
Explore all communication servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up MCP Telegram in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use MCP Telegram?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.