Telegram

You can run a Telegram MCP Server that talks to Telegram through mtcute, letting you send messages, read chats, search history, and manage dialogs from an MCP client. This guide walks you through installation, first-time setup, and practical usage patterns so you can automate Telegram interactions reliably.

How to use

Connect your MCP client to the Telegram MCP server by configuring a local stdio server entry that runs the Telegram MCP executable. You provide Telegram API credentials and a storage path for the authenticated session. Once connected, you can use the available tools to send messages, fetch history, search messages, list dialogs, and observe recent activity across chats.

How to install

Prerequisites: you need a Node-like runtime or bun to install and run the server components, and you must complete an initial Telegram login to create an authenticated session.

Option 1: Download Pre-built Binary

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, then build the executable.

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)

1. Obtain Telegram API credentials from https://my.telegram.org. 2. Run the initial setup to authenticate with Telegram using the credentials and to generate a storage path for the authenticated session.

Set the credentials and start the server for the first time. The server will prompt for your phone number, send a verification code via Telegram, ask for the code, and display the absolute storage path for the session.

Example: the storage path will resemble: /Users/username/telegram-mcp/bot-data/session

Usage with a client

Configure your MCP client to run the Telegram MCP server locally. You will provide the path to the executable and the required environment variables so the client can authenticate and manage sessions.

The following JSON config shows a typical setup to run the server locally. Replace the absolute storage path with the one displayed during initial setup.

json
{
  "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"
      }
    }
  }
}

Notes about configuration and running

The server stores session data in the bot-data directory created during first-time setup. Use the absolute path shown when prompted as TELEGRAM_STORAGE_PATH in your MCP client configuration.

Available tools

messages_sendText

Send a text message to a chat or user. Requires chatId and text; optionally you can specify a replyToMessageId.

messages_getHistory

Retrieve message history from a specific chat. Provide chatId, with optional limit and offsetId for pagination.

messages_search

Search messages across chats or within a specific chat using a query. Supports optional chatId and limit.

messages_getRecent

Fetch recent messages from all chats, with limits on the number of chats and messages per chat.

wait_for_reply

Wait for the next incoming message in a specified chat within a timeout period.

dialogs_list

List all dialogs (chats) with optional filters to limit to users, groups, or channels.

dialogs_getInfo

Get detailed information for a specific dialog by chatId