home / mcp / mcp telegram server

MCP Telegram Server

MCP Server for Telegram

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "dryeab-mcp-telegram": {
      "command": "mcp-telegram",
      "args": [
        "start"
      ],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

You can connect Large Language Models to Telegram through the Model Context Protocol (MCP). This server lets AI agents interact with Telegram to send, edit, delete messages, search chats, manage drafts, download media, and more using MTProto, enabling powerful automation and assistant-driven workflows.

How to use

Set up your MCP client to connect with the Telegram MCP server. Start the MCP server from your terminal, then configure your MCP client to point to that local process. Once connected, you can command AI agents to perform common Telegram actions such as sending messages, editing content, retrieving chat history, and handling drafts and media.

How to install

Prerequisites: Install Python 3.10 or higher and follow the official uv guide to install uv for running MCP tools.

Install the MCP Telegram CLI tool with uv.

uv tool install mcp-telegram

Additional setup and configuration

Login to Telegram from the MCP Telegram CLI to authorize access to your account. You will be prompted for your API ID, API Hash, phone number, verification code, and 2FA if enabled. Your credentials are stored in a session file for future use.

Create an MCP configuration that points your MCP client to the local Telegram MCP server. The following configuration starts the MCP server through the MCP CLI and passes the required API credentials as environment variables.

{
  "mcpServers": {
    "mcp_telegram": {
      "command": "mcp-telegram",
      "args": ["start"],
      "env": {
        "API_ID": "<your_api_id>",
        "API_HASH": "<your_api_hash>"
      }
    }
  }
}

Security and session management

Keep your API credentials private. Do not share your API_ID or API_HASH publicly. Use the logout or clear-session commands when you need to remove credentials from the local machine.

Troubleshooting

If you encounter database locked errors from Telethon when running multiple instances, ensure only one MCP Telegram process uses the session file at a time. If you need to stop a stuck process, force-stop the MCP Telegram instance appropriate to your operating system.

Contributing

Contributions are welcome. Share issues, feature requests, and pull requests to improve MCP Telegram for everyone.

License

This project is licensed under the MIT License.

Available tools

send_message

Send text messages or files to any user, group, or channel.

edit_message

Modify the content of previously sent messages.

delete_message

Remove one or multiple messages.

get_messages

Retrieve message history with filtering options.

search_dialogs

Find users, groups, and channels by name or username.

message_from_link

Access specific messages using Telegram links.

get_draft

View current message draft for any chat.

set_draft

Create or clear message drafts.

media_download

Download photos, videos, and documents from messages.