mcp-telegram 0.1.11

Connect Large Language Models to Telegram via the Model Context Protocol (MCP).

Built with Telethon, this server allows AI agents to interact with Telegram, enabling features like sending/editing/deleting messages, searching chats, managing drafts, downloading media, and more using the MTProto.

🚀 Getting Started

Prerequisites

• Python 3.10 or higher
• uv Install via the official uv guide.

Installation

Install the mcp-telegram CLI tool:

uv tool install mcp-telegram

⚙️ Usage

The mcp-telegram command-line tool is your entry point.

mcp-telegram --help # See all commands

Login

First, authenticate with your Telegram account:

mcp-telegram login

This interactive command will prompt you for:

• API ID & API Hash: Obtain these from my.telegram.org/apps.
• Phone Number: Your Telegram-registered phone number (international format, e.g., +1234567890).
• Verification Code: Sent to your Telegram account upon first login.
• 2FA Password: If you have Two-Factor Authentication enabled.

Your credentials are securely stored in the session file for future use.

Connect to the MCP server

To use MCP Telegram with MCP clients like Claude Desktop or Cursor, you'll need to configure the MCP server. The configuration process varies by client and operating system.

For detailed setup instructions, please refer to:

• Claude Desktop MCP Setup Guide
• Cursor MCP Documentation

The configuration file should contain:

{
  "mcpServers": {
    "mcp-telegram": {
      "command": "mcp-telegram" /* Use full path if client can't find the command (e.g. "/usr/local/bin/mcp-telegram"). See IMPORTANT section below for full path instructions. */,
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

After saving the configuration file, restart your application.

🧰 Available Tools

Here's a comprehensive list of tools you can use to interact with Telegram through MCP:

📨 Messaging Tools

Tool	Description
send_message	✉️ Send text messages or files to any user, group, or channel
edit_message	✏️ Modify content of previously sent messages
delete_message	🗑️ Remove one or multiple messages
get_messages	📜 Retrieve message history with advanced filtering options

🔍 Search & Navigation

Tool	Description
search_dialogs	🔎 Find users, groups, and channels by name or username
message_from_link	🔗 Access specific messages using Telegram links

📝 Draft Management

Tool	Description
get_draft	📋 View current message draft for any chat
set_draft	✍️ Create or clear message drafts

📂 Media Handling

Tool	Description
media_download	📸 Download photos, videos, and documents from messages

🛠️ Troubleshooting

Database Locked Errors

Running multiple mcp-telegram instances using the same session file can cause database is locked errors due to Telethon's SQLite session storage. Ensure only one instance uses a session file at a time.

Force-Stopping Existing Processes

If you need to stop potentially stuck processes:

• macOS / Linux: pkill -f "mcp-telegram"
• Windows: taskkill /F /IM mcp-telegram.exe /T (Check Task Manager for the exact process name)

🤝 Contributing

We welcome contributions! If you'd like to help improve MCP Telegram, please feel free to submit issues, feature requests, or pull requests. Your feedback and contributions help make this project better for everyone.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---