Telegram
Enables interaction with Telegram channels through the Bot API, supporting comprehensive messaging operations including sending text/photos, creating polls, managing reactions, and editing/deleting messages. Provides complete channel management capab
What is Telegram?
Telegram is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to enables interaction with telegram channels through the bot api, supporting comprehensive messaging operations including sending text/photos, creating polls, managing reactions, and editing/deleting me...
Enables interaction with Telegram channels through the Bot API, supporting comprehensive messaging operations including sending text/photos, creating polls, managing reactions, and editing/deleting messages. Provides complete channel management capab
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Enables interaction with Telegram channels through the Bot A
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx telegram-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Telegram
The Telegram MCP Server connects AI assistants to your personal Telegram account using the Telethon library and official Telegram API, exposing over 80 tools for messaging, media, contacts, group management, and more. Unlike bot-only integrations, it authenticates as a real user account, giving your AI access to private chats, channels, groups, and contact lists. It is ideal for automating message workflows, monitoring conversations across multiple accounts, and orchestrating Telegram-based communications from within Claude or another MCP client.
Prerequisites
- Python 3.10+ and the uv package manager installed
- Telegram API credentials (API_ID and API_HASH) from https://my.telegram.org/apps
- A generated session string (run session_string_generator.py after cloning the repo)
- An MCP client such as Claude Desktop or Claude Code
Clone the repository
Clone the telegram-mcp repository from GitHub. Do NOT install from PyPI — the package there is unrelated and poses credential risks.
git clone https://github.com/chigwell/telegram-mcp.git
cd telegram-mcp
uv syncObtain Telegram API credentials
Log in to https://my.telegram.org/apps with your Telegram account, create an application, and note your API ID and API Hash. These are required environment variables.
Generate a session string
Run the session string generator script, which walks you through authenticating via QR code or phone number. Copy the resulting string — it authenticates the server as your Telegram account.
uv run session_string_generator.py
# or with QR code:
uv run session_string_generator.py --qr
# or with phone number:
uv run session_string_generator.py --phoneConfigure your MCP client
Add the server to your claude_desktop_config.json, passing the three required environment variables. Optionally set TELEGRAM_EXPOSED_TOOLS to 'read-only' to restrict write capabilities.
{
"mcpServers": {
"telegram": {
"command": "uv",
"args": ["run", "/path/to/telegram-mcp/main.py"],
"env": {
"TELEGRAM_API_ID": "your_api_id",
"TELEGRAM_API_HASH": "your_api_hash",
"TELEGRAM_SESSION_STRING": "your_session_string",
"TELEGRAM_EXPOSED_TOOLS": "all"
}
}
}
}Restart your MCP client and verify
Restart Claude Desktop or your MCP client. Ask it to list your Telegram chats or send a test message to confirm the server is connected and authenticated.
Telegram Examples
Client configuration
Example claude_desktop_config.json entry for Telegram MCP Server using uv to run the local Python server.
{
"mcpServers": {
"telegram": {
"command": "uv",
"args": ["run", "/path/to/telegram-mcp/main.py"],
"env": {
"TELEGRAM_API_ID": "12345678",
"TELEGRAM_API_HASH": "abcdef1234567890abcdef1234567890",
"TELEGRAM_SESSION_STRING": "1BVtsOKABu...",
"TELEGRAM_EXPOSED_TOOLS": "all"
}
}
}
}Prompts to try
Example prompts that leverage the 80+ Telegram tools exposed by this server.
- "List all my Telegram accounts and show unread message counts for each"
- "Send a message to @username saying 'Meeting at 3pm tomorrow'"
- "Search my chat history with the 'Project Alpha' group for mentions of the deadline"
- "Forward the last message from the 'Announcements' channel to my 'Team' group"
- "Create a poll in the 'Feedback' channel asking which day works best for a meeting"Troubleshooting Telegram
Authentication fails or session string is rejected
Regenerate the session string by re-running session_string_generator.py. Ensure TELEGRAM_API_ID and TELEGRAM_API_HASH match exactly the credentials from my.telegram.org/apps for the app you created.
Tools are not appearing or the server fails to start
Verify you ran 'uv sync' inside the cloned repo directory and that the path in your MCP config points to the correct main.py. Never install via pip or uvx — those packages are unrelated.
Two-factor authentication or flood wait errors
If your account has 2FA enabled, the session generator will prompt for your password. Flood wait errors (420) mean Telegram is rate-limiting requests — wait the indicated number of seconds before retrying.
Frequently Asked Questions about Telegram
What is Telegram?
Telegram is a Model Context Protocol (MCP) server that enables interaction with telegram channels through the bot api, supporting comprehensive messaging operations including sending text/photos, creating polls, managing reactions, and editing/deleting messages. provides complete channel management capab It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Telegram?
Follow the installation instructions on the Telegram GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Telegram?
Telegram works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Telegram free to use?
Yes, Telegram is open source and available under the Apache-2.0 license. You can use it freely in both personal and commercial projects.
Telegram Alternatives — Similar Communication Servers
Looking for alternatives to 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 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 Telegram?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.