Telegram MCP server

The server is a bridge between the Telegram API and the AI assistants and is based on the Model Context Protocol.

[!IMPORTANT]Ensure that you have read and understood the Telegram API Terms of Service before using this server.Any misuse of the Telegram API may result in the suspension of your account.

What is MCP?
What does this server do?
Installation
- From Releases
  - macOS
  - Linux
  - Windows
- From Source
Configuration
- Telegram API Configuration
- Client Configuration

What is MCP?

The Model Context Protocol (MCP) is a system that lets AI apps, like Claude Desktop or Cursor, connect to external tools and data sources. It gives a clear and safe way for AI assistants to work with local services and APIs while keeping the user in control.

What does this server do?

Get current user data
Get the list of dialogs (chats, channels, groups)
Get the list of (unread) messages in the given dialog
Mark chanel as read
Retrieve messages by date and time
Get the list of contacts
Draft a message

Installation

From Releases

macOS

Note: The command above install to /usr/local/bin. To install elsewhere, replace /usr/local/bin with your preferred directory in your PATH.

# Intel Mac (x86_64)
curl -L https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_x86_64.tar.gz | tar xz -C /usr/local/bin

# Apple Silicon (M1/M2)
curl -L https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_arm64.tar.gz | tar xz -C /usr/local/bin

Linux

Note: The commands install to /usr/local/bin. To install elsewhere, replace /usr/local/bin with your preferred directory in your PATH.

# x86_64 (64-bit)
curl -L https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_x86_64.tar.gz | tar xz -C /usr/local/bin

# ARM64
curl -L https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_arm64.tar.gz | tar xz -C /usr/local/bin

Windows

Download the latest release for your architecture:
- Windows x64
- Windows ARM64
Extract the .zip file
Add the extracted directory to your PATH or move telegram-mcp.exe to a directory in your PATH

From Source

Requirements:

Go 1.24 or later
GOBIN in PATH

go install github.com/chaindead/telegram-mcp@latest

Configuration

Telegram API Configuration

Before you can use the server, you need to connect to the Telegram API.

Get the API ID and hash from Telegram API
Run the following command:
```
telegram-mcp auth --app-id <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>
```
Enter the code you received from Telegram to connect to the API.

The password may be required if you have two-factor authentication enabled.

Client Configuration

Example of Configuring Claude Desktop to recognize the Telegram MCP server.

Open the Claude Desktop configuration file:
- in MacOS, the configuration file is located at ~/Library/Application Support/Claude/claude_desktop_config.json
- in Windows, the configuration file is located at %APPDATA%\Claude\claude_desktop_config.json
Note:You can also find claude_desktop_config.json inside the settings of Claude Desktop app

Add the server configuration

for Claude desktop:

 {
   "mcpServers": {
     "telegram": {
       "command": "telegram-mcp",
       "env": {
         "TG_APP_ID": "<your-app-id>",
         "TG_API_HASH": "<your-api-hash>",
         "PATH": "<path_to_telegram-mcp_binary_dir>",
         "HOME": "<path_to_your_home_directory"
       }
     }
   }
 }

for Cursor:

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "telegram-mcp",
      "env": {
        "TG_APP_ID": "<your-app-id>",
        "TG_API_HASH": "<your-api-hash>"
      }
    }
  }
}

Telegram MCP server