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

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

Clone the repository and install dependencies:

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

Build the executable:
```
bun run build
```

Initial Setup (First Time Only)

Get your Telegram API credentials from https://my.telegram.org
Run the initial setup to authenticate with Telegram:
```
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)
Note the storage path displayed in the output. It will look something like:
```
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)

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

Development

Run in development mode:

bun run dev

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