Telegram MCP Server

What is Telegram MCP Server about?

The server acts as a bridge between the Telegram API and AI assistants, exposing tools that let assistants list dialogs, fetch messages, mark chats as read, and send drafts.

How to use Telegram MCP Server?

Install – use Homebrew, NPX, binary releases, or build from source.
Authorize – run telegram-mcp auth --app-id <API_ID> --api-hash <API_HASH> --phone <PHONE> (add --password for 2FA or --new to reset session).
Configure the client – add an entry to the MCP server list of your AI tool (e.g., Claude Desktop) pointing to the telegram-mcp command and provide TG_APP_ID and TG_API_HASH as environment variables.
Invoke tools – AI assistants can call tools such as tg_me, tg_dialogs, tg_read, tg_dialog, and tg_send to interact with Telegram.

Key features of Telegram MCP Server

Retrieve current account information (tg_me).
List dialogs with optional unread filter (tg_dialogs).
Mark a dialog as read (tg_read).
Fetch messages from a specific dialog (tg_dialog).
Send draft messages to any dialog (tg_send).
Cross‑platform binaries (macOS, Linux, Windows) and NPX execution.

Use cases of Telegram MCP Server

Personal assistants: Summarize unread messages and draft replies.
Workflows: Automatically monitor specific chats for keywords or topics.
Organization: Analyze chat history to suggest folder structures or importance rankings.
Customer support: Detect unanswered questions and generate response drafts.

FAQ from the Telegram MCP Server

Do I need a Telegram developer account? Yes, you must obtain an API ID and hash from https://my.telegram.org.
Can I run the server on Windows? Yes, use the provided Windows binaries or NPX.
What if I change my phone number? Re‑run the auth command with the new number; the server will create a new session.
Is there a limit on message fetch size? The server follows Telegram API limits; large dialogs may need pagination via additional parameters.
How do I update the binary? For Homebrew users run brew upgrade chaindead/tap/telegram-mcp; for NPX simply reinstall.

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?
- Capabilities
- Prompt examples
Installation
- Homebrew
- NPX
- From Releases
  - MacOS
  - Linux
  - Windows
- From Source
Configuration
- Authorization
- Client Configuration
Star History

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?

Capabilities

Get current account information (tool: tg_me)
List dialogs with optional unread filter (tool: tg_dialogs)
Mark dialog as read (tool: tg_read)
Retrieve messages from specific dialog (tool: tg_dialog)
Send draft messages to any dialog (tool: tg_send)

Prompt examples

Here are some example prompts you can use with AI assistants:

Message Management

"Check for any unread important messages in my Telegram"
"Summarize all my unread Telegram messages"
"Read and analyze my unread messages, prepare draft responses where needed"
"Check non-critical unread messages and give me a brief overview"

Organization

"Analyze my Telegram dialogs and suggest a folder structure"
"Help me categorize my Telegram chats by importance"
"Find all work-related conversations and suggest how to organize them"

Communication

"Monitor specific chat for updates about [topic]"
"Draft a polite response to the last message in [chat]"
"Check if there are any unanswered questions in my chats"

Installation

Homebrew

You can install a binary release on macOS/Linux using brew:

# Install
brew install chaindead/tap/telegram-mcp

# Update
brew upgrade chaindead/tap/telegram-mcp

NPX

You can run the latest version directly using npx (supports macOS, Linux, and Windows):

npx -y @chaindead/telegram-mcp

When using NPX, modify the standard commands and configuration as follows:

Authentication command becomes:

npx -y @chaindead/telegram-mcp auth ...

Claude MCP server configuration becomes:

{
  "mcpServers": {
    "telegram": {
      "command": "npx",
      "args": ["-y", "@chaindead/telegram-mcp"],
      "env": {
        "TG_APP_ID": "<your-api-id>",
        "TG_API_HASH": "<your-api-hash>"
      }
    }
  }
}

For complete setup instructions, see Authorization and Client Configuration.

From Releases

MacOS

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

First, download the archive for your architecture:

# For Intel Mac (x86_64)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_x86_64.tar.gz

# For Apple Silicon (M1/M2)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Darwin_arm64.tar.gz

Then install the binary:

# Extract the binary
sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin

# Make it executable
sudo chmod +x /usr/local/bin/telegram-mcp

# Clean up
rm telegram-mcp.tar.gz

Linux

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

First, download the archive for your architecture:

# For x86_64 (64-bit)
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_x86_64.tar.gz

# For ARM64
curl -L -o telegram-mcp.tar.gz https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Linux_arm64.tar.gz

Then install the binary:

# Extract the binary
sudo tar xzf telegram-mcp.tar.gz -C /usr/local/bin

# Make it executable
sudo chmod +x /usr/local/bin/telegram-mcp

# Clean up
rm telegram-mcp.tar.gz

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

Authorization

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:

Note: If you have 2FA enabled: add --password <2fa_password>

Note: If you want to override existing session: add --new
```
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.
Done! Please give this project a ⭐️ to support its development.

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