Simple Telegram MCP
✨ Example use cases
- Automate tasks: “Look up the weather forecast and send it to my family group”
- Stay on top of things: “Review my unread messages, give me the highlights, and queue polite replies”
- Polish before sending: “Read Tony’s latest note in the Family channel, craft three informal reply drafts, and leave them for me to send.”
🚀 Quick Start
Automatic client configuration
| Client | Command |
|---|---|
| Cursor | uvx simple-telegram-mcp --install cursor |
| Claude Desktop | uvx simple-telegram-mcp --install claude-desktop |
| Claude Code | uvx simple-telegram-mcp --install claude-code |
| Gemini CLI | uvx simple-telegram-mcp --install gemini-cli |
| VS Code (global) | uvx simple-telegram-mcp --install vscode |
| MCP JSON (stdout) | uvx simple-telegram-mcp --install mcp-json |
| OpenAI Codex CLI | uvx simple-telegram-mcp --install codex-cli |
Authorize Telegram
uvx simple-telegram-mcp --login
✨ Heads-up: the login flow is zero drama. You’ll pop in your phone number, Telegram will DM you a code, you paste it back here, and you’re in.
💡 When using Simple Telegram MCP through an assistant, run
telegram_auth_startfollowed bytelegram_auth_confirmright inside the conversation as soon as anAUTH_REQUIREDmessage appears. The assistant will guide you through entering your phone, code, and (if needed) two-factor password.
🛠️ Tools
| Tool | Description |
|---|---|
telegram_add_reaction |
Adds an emoji reaction to a specific message. |
telegram_auth_start |
Sends a Telegram login code to begin the interactive auth flow. |
telegram_auth_confirm |
Confirms the login code (and optional 2FA password) to finish authentication. |
telegram_auth_status |
Reports whether the session is authorized or awaiting confirmation. |
telegram_get_chat_history |
Retrieves recent messages for a chat. |
telegram_get_draft |
Returns the current unsent draft for a chat, if one exists. |
telegram_get_user_profile |
Fetches profile information for a user. |
telegram_list_chats |
Lists dialogs (DMs, groups, channels) the account can access. |
telegram_login_status |
Reports connection and authorization status. |
telegram_post_message |
Sends a new message to a chat. |
telegram_reply_to_message |
Replies to a message by ID. |
telegram_save_draft |
Stores or updates a draft message without sending it. |
telegram_search_chats |
Finds chats by partial name or username. |
search_telegram_messages |
Searches globally (or within a chat) for messages containing text. |
🧾 Resources
| Resource URI | Description |
|---|---|
telegram://chats |
Latest 25 dialogs with names, types, and unread counts. |
telegram://session/status |
Connection and authorization snapshot. |
telegram://chats/{chat_id}/unread |
Incoming unread messages for a chat (oldest first). |
telegram://chats/{chat_id}/history |
Recent message history for a chat. |
🧠 Prompts
telegram/draft-reply– Generates a concise reply in the tone you request.telegram/check-session– Reminds the assistant to verify the session before doing anything else.
✅ Testing
- Fast unit tests (default):
uv run pytest -q - Integration tests:
RUN_TELEGRAM_TESTS=1 uv run pytest -m integration -q(make sure to log in first:uvx simple-telegram-mcp --login)
1 maintainer
Metadata
1 maintainer
Release files for simple-telegram-mcp 0.1.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| simple_telegram_mcp-0.1.10.tar.gz | 1.3 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| simple_telegram_mcp-0.1.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.3 MB
Release files / simple_telegram_mcp-0.1.10.tar.gz
| Download URL | simple_telegram_mcp-0.1.10.tar.gz |
|---|---|
| Size | 1.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
80bbb58011f611696a2144d0537cdf75ae05e3c7d791205a47ea9416824d551c
|
|
BLAKE2b-256 checksum How to use checksums |
88a53808a28a666169a73ec1cc10bda3b98a6b1655ae63bea3df4e677ddfdbb3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.6.14
|
Release files / simple_telegram_mcp-0.1.10-py3-none-any.whl
| Download URL | simple_telegram_mcp-0.1.10-py3-none-any.whl |
|---|---|
| Size | 18.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
18f6d68a7681ee3fc7a85ffa7c2bf509df0fccbdf848f25c46e9c913fb681ce4
|
|
BLAKE2b-256 checksum How to use checksums |
76776ec9b7e84596d46267a75e5d9c0957419619589f8f5fbed758752b5ea8af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.6.14
|
