https://github.com/chaindead/telegram-mcp

MCP server to work with Telegram through MTProto
https://github.com/chaindead/telegram-mcp

Last synced: about 18 hours ago
JSON representation

MCP server to work with Telegram through MTProto

Host: GitHub
URL: https://github.com/chaindead/telegram-mcp
Owner: chaindead
License: mit
Created: 2025-04-01T14:43:04.000Z (6 months ago)
Default Branch: main
Last Pushed: 2025-04-08T16:58:40.000Z (6 months ago)
Last Synced: 2025-04-08T17:49:06.990Z (6 months ago)
Language: Go
Size: 51.8 KB
Stars: 8
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

awesome-mcp-servers - telegram-mcp - Telegram MCP server for API integration, supporting user data access, chat management, and message retrieval, making it a top MCP server for Telegram connectivity. ([Read more](/details/telegram-mcp.md)) `mcp` `telegram` `messaging` `api-integration` (Messaging MCP Servers)
best-of-mcp-servers - GitHub - 80% open · ⏱️ 21.08.2025) (Communication)
awesome-mcp-servers - **telegram-mcp** - Telegram MCP for managing dialogs, messages, drafts, read statuses, and more. `go` `mcp` `mcp-server` `mtproto` `telegram` `go install chaindead/telegram-mcp@latest` (DevOps)
awesome-mcp-servers - **telegram-mcp** - Telegram MCP for managing dialogs, messages, drafts, read statuses, and more. `go` `mcp` `mcp-server` `mtproto` `telegram` `go install chaindead/telegram-mcp@latest` (DevOps)
mcp-index - Telegram MCP server - Connects AI assistants to the Telegram API for seamless interaction. Enables retrieval of user data, management of dialogs, and interaction with messages. (Virtual Assistants)
awesome-mcp-zh - chaindead/telegram-mcp

README

          [![](https://badge.mcpx.dev?type=server 'MCP Server')](https://github.com/punkpeye/awesome-mcp-servers?tab=readme-ov-file#communication)

[![](https://img.shields.io/badge/OS_Agnostic-Works_Everywhere-purple)](https://github.com/chaindead/telegram-mcp?tab=readme-ov-file#installation)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Visitors](https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Fchaindead%2Ftelegram-mcp&label=Visitors&labelColor=%23d9e3f0&countColor=%23697689&style=flat&labelStyle=none)](https://visitorbadge.io/status?path=https%3A%2F%2Fgithub.com%2Fchaindead%2Ftelegram-mcp)

# Telegram MCP server

The server is a bridge between the Telegram API and the AI assistants and is based on the [Model Context Protocol](https://modelcontextprotocol.io).

> [!IMPORTANT]

> Ensure that you have read and understood the [Telegram API Terms of Service](https://core.telegram.org/api/terms) before using this server.

> Any misuse of the Telegram API may result in the suspension of your account.

## Table of Contents

- [What is MCP?](#what-is-mcp)

- [What does this server do?](#what-does-this-server-do)

  - [Capabilities](#capabilities)

  - [Prompt examples](#prompt-examples)

    - [Message Management](#message-management)

    - [Organization](#organization)

    - [Communication](#communication)

- [Installation](#installation)

  - [Homebrew](#homebrew)

  - [NPX](#npx)

  - [From Releases](#from-releases)

    - [MacOS](#macos)

    - [Linux](#linux)

    - [Windows](#windows)

  - [From Source](#from-source)

- [Configuration](#configuration)

  - [Authorization](#authorization)

  - [Client Configuration](#client-configuration)

- [Star History](#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

- [x] Get current account information (`tool: tg_me`)

- [x] List dialogs with optional unread filter (`tool: tg_dialogs`)

- [x] Mark dialog as read (`tool: tg_read`)

- [x] Retrieve messages from specific dialog (`tool: tg_dialog`)

- [x] 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:

```bash

# 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):

```bash

npx -y @chaindead/telegram-mcp

```

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

- [Authentication command](#authorization) becomes:

```bash

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

```

- [Claude MCP server configuration](#client-configuration) becomes:

```json

{

  "mcpServers": {

    "telegram": {

      "command": "npx",

      "args": ["-y", "@chaindead/telegram-mcp"],

      "env": {

        "TG_APP_ID": "",

        "TG_API_HASH": ""

      }

    }

  }

}

```

For complete setup instructions, see [Authorization](#authorization) and [Client Configuration](#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:

```bash

# 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:

```bash

# 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:

```bash

# 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:

```bash

# 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

#### Windows

1. Download the latest release for your architecture:

   - [Windows x64](https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Windows_x86_64.zip)

   - [Windows ARM64](https://github.com/chaindead/telegram-mcp/releases/latest/download/telegram-mcp_Windows_arm64.zip)

2. Extract the `.zip` file

3. 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

```bash

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

```

## Configuration

### Authorization

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

1. Get the API ID and hash from [Telegram API](https://my.telegram.org/auth)

2. Run the following command:

   > __Note:__

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

   >  __Note:__

   > If you want to override existing session: add --new

   ```bash

   telegram-mcp auth --app-id  --api-hash  --phone 

   ```

   📩 Enter the code you received from Telegram to connect to the API.

3. Done! Please give this project a ⭐️ to support its development.

### Client Configuration

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

1. 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

2. Add the server configuration

   

   for Claude desktop:

   ```json

    {

      "mcpServers": {

        "telegram": {

          "command": "telegram-mcp",

          "env": {

            "TG_APP_ID": "",

            "TG_API_HASH": "",

            "PATH": "",

            "HOME": "",

            "TG_API_HASH": ""

          }

        }

      }

    }

    ```

## Star History

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/chaindead/telegram-mcp

Awesome Lists containing this project

README