telegram-mcp

A Model Context Protocol (MCP) server for interacting with Telegram using mtcute.

Features

• Send text messages to chats
• Wait for incoming messages in specific chats
• Read messages from chats
• Search messages
• List and get information about dialogs (chats)
• Get recent messages across all chats
• Set and inspect emoji-status IDs for accounts and channels

Development

Run in development mode:

bun run dev

The server stores session data in bot-data/ directory.

Setup

Installation

Option 1: Download Pre-built Binary

Download the latest release for your platform from the releases page:

• macOS (Apple Silicon): telegram-mcp-darwin-arm64.tar.gz
• macOS (Intel): telegram-mcp-darwin-x64.tar.gz
• Linux: telegram-mcp-linux-x64.tar.gz
• Windows: telegram-mcp-win-x64.exe.zip

Extract the archive and make the binary executable (Unix systems):

tar -xzf telegram-mcp-*.tar.gz
chmod +x telegram-mcp

Option 2: Build from Source

1. Clone the repository and install dependencies:

   Copy

   git clone git@github.com:zhigang1992/telegram-mcp.git
   cd telegram-mcp
   bun install

2. Build the executable:

   Copy

   bun run build

Initial Setup (First Time Only)

1. Get your Telegram API credentials from https://my.telegram.org

2. Run the initial setup to authenticate with Telegram:

   Copy

   export API_ID=your_api_id
   export API_HASH=your_api_hash
   ./telegram-mcp

   The server will:

   • Prompt you to enter your phone number
   • Send you a verification code via Telegram
   • Ask for the verification code
   • Display the absolute storage path (you'll need this for MCP configuration)

3. Note the storage path displayed in the output. It will look something like:

   Copy

   Storage path: /Users/username/telegram-mcp/bot-data/session

Usage

As an MCP Server

Add to your Claude Desktop config using the storage path from the initial setup:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/telegram-mcp",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "TELEGRAM_STORAGE_PATH": "/absolute/path/from/initial/setup"
      }
    }
  }
}

Important: The TELEGRAM_STORAGE_PATH must be the absolute path shown during initial setup. This ensures the MCP server uses the authenticated session.

Available Tools

Message Tools

• messages_sendText - Send a text message to a chat

  • chatId (required): Chat/User ID or username
  • text (required): Message text to send
  • replyToMessageId: Optional message ID to reply to

• messages_getHistory - Get message history from a chat

  • chatId (required): Chat/User ID or username
  • limit: Number of messages (default: 100, max: 100)
  • offsetId: Message ID for pagination

• messages_search - Search for messages

  • query (required): Search query
  • chatId: Specific chat to search in (optional)
  • limit: Number of results (default: 50)

• messages_getRecent - Get recent messages from all chats

  • limit: Number of chats (default: 10)
  • messagesPerChat: Messages per chat (default: 10)

Interactive Tools

• wait_for_reply - Wait for the next message in a chat
  • chatId (required): Chat/User ID or username to wait for a message from
  • timeoutSeconds: Timeout in seconds (default: 60, max: 300)

Status Tools

• status_getCurrent - Get the current emoji status for a peer

  • peerId: Target peer, defaults to self

• status_setEmoji - Set or clear an emoji status

  • peerId: Target peer, defaults to self
  • emojiId: Custom emoji document ID, required unless clear=true
  • isCollectible: Set true when emojiId is a collectible ID
  • until: Optional ISO-8601 timestamp or Unix timestamp string
  • clear: Clear the current status instead of setting one

• status_listAvailable - List available default emoji-status IDs

  • scope: self or channel (default: self)
  • limit: Maximum IDs to return (default: 100)

• status_listCollectibles - List owned collectible IDs usable as self emoji statuses

  • owner: Peer to inspect, defaults to self
  • limit: Maximum collectibles to return (default: 100)

Dialog Tools

• dialogs_list - List all dialogs

  • limit: Maximum dialogs (default: 50)
  • filter: Filter options (onlyUsers, onlyGroups, onlyChannels)

• dialogs_getInfo - Get detailed dialog information

  • chatId (required): Chat/User ID or username