Telegram MCP
An MCP server that enables interaction with Telegram to send, read, and search messages across chats and dialogs. It supports waiting for incoming messages and retrieving conversation history through natural language commands.
What is Telegram MCP?
Telegram MCP is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to mcp server that enables interaction with telegram to send, read, and search messages across chats and dialogs. it supports waiting for incoming messages and retrieving conversation history through nat...
An MCP server that enables interaction with Telegram to send, read, and search messages across chats and dialogs. It supports waiting for incoming messages and retrieving conversation history through natural language commands.
This server falls under the Communication category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- An MCP server that enables interaction with Telegram to send
Use Cases
Maintainer
Works with
Installation
NPM
npx -y telegramManual Installation
npx -y telegramConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Telegram MCP
Telegram MCP is a Go-based MCP server that connects AI assistants to your personal Telegram account via the MTProto protocol, enabling them to list conversations, read message history, send draft messages, and mark chats as read through natural language commands. Unlike bot-based integrations, it authenticates as a real Telegram user account using the official API, giving it access to all your personal chats, groups, and channels. It is particularly useful for summarizing unread messages across many dialogs, drafting replies, and searching conversation history without manually switching to the Telegram app.
Prerequisites
- A Telegram account and phone number
- Telegram API credentials: obtain TG_APP_ID and TG_API_HASH from https://my.telegram.org/auth by creating an application
- Go 1.24+ if building from source, or Homebrew on macOS for a pre-built binary
- An MCP client such as Claude Desktop or Claude Code
Obtain Telegram API credentials
Go to https://my.telegram.org/auth, log in with your phone number, click API development tools, and create a new application. Note the App api_id and App api_hash values — these are your TG_APP_ID and TG_API_HASH.
Install the telegram-mcp binary
On macOS, install via Homebrew. On other platforms, download a pre-built binary from GitHub Releases, or build from source with Go 1.24+.
# macOS via Homebrew:
brew install chaindead/tap/telegram-mcp
# Or via npx (cross-platform):
npx -y @chaindead/telegram-mcp
# Or build from source:
go install github.com/chaindead/telegram-mcp@latestAuthorize your Telegram account
Run the auth command with your API credentials and phone number. You will receive an SMS or Telegram code to complete authorization. Add --password if your account has two-factor authentication enabled.
telegram-mcp auth --app-id YOUR_APP_ID --api-hash YOUR_API_HASH --phone +1234567890Add the server to your MCP client configuration
Register the server in your claude_desktop_config.json with the TG_APP_ID and TG_API_HASH environment variables. After authorization, session data is stored locally so no phone code is needed on subsequent launches.
Restart your MCP client and verify
Restart Claude Desktop or reload your MCP client. Ask it to list your Telegram dialogs to confirm the connection is working.
Telegram MCP Examples
Client configuration
Add this block to your claude_desktop_config.json with your Telegram API credentials.
{
"mcpServers": {
"telegram": {
"command": "telegram-mcp",
"args": [],
"env": {
"TG_APP_ID": "your_app_id_here",
"TG_API_HASH": "your_api_hash_here"
}
}
}
}Prompts to try
These prompts use the tg_dialogs, tg_dialog, tg_send, tg_read, and tg_me tools to interact with your Telegram account.
- "List all my unread Telegram conversations and summarize each one"
- "Read the last 20 messages from my conversation with John and tell me what we discussed"
- "Draft a reply to the message from Sarah saying I'll be 10 minutes late"
- "Mark all my unread chats as read"
- "Search my Telegram chats for any messages mentioning the project deadline"Troubleshooting Telegram MCP
Authorization fails with 'phone number invalid' error
Ensure the phone number is in international format with the country code, e.g., +14155552671. Do not include spaces or dashes. Also verify TG_APP_ID is a number and TG_API_HASH is the full hex string from my.telegram.org.
Server starts but tg_dialogs returns an empty list
The session may not have completed authorization. Re-run `telegram-mcp auth` with your credentials and phone number to generate a fresh session. If you have 2FA enabled, add the --password flag.
telegram-mcp binary not found after Homebrew install
Run `brew update && brew upgrade chaindead/tap/telegram-mcp` to ensure the latest version is installed. Then run `which telegram-mcp` to confirm the binary is on your PATH. You may need to add the Homebrew bin directory to your shell profile.
Frequently Asked Questions about Telegram MCP
What is Telegram MCP?
Telegram MCP is a Model Context Protocol (MCP) server that mcp server that enables interaction with telegram to send, read, and search messages across chats and dialogs. it supports waiting for incoming messages and retrieving conversation history through natural language commands. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Telegram MCP?
Install via npm with the command: npx -y 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 Telegram MCP?
Telegram MCP works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Telegram MCP free to use?
Yes, Telegram MCP is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Telegram MCP Alternatives — Similar Communication Servers
Looking for alternatives to Telegram MCP? 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 MCP 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 MCP?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.