# chaindead/telegram-mcp [Health: Active]

**Category:** 💬 Communication  
**Repository:** https://github.com/chaindead/telegram-mcp  
**GitHub Stars:** 349  
**npm Downloads (last month):** 2713  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/chaindead-telegram-mcp

## Description
Telegram API integration for accessing user data, managing dialogs (chats, channels, groups), retrieving messages, and handling read status

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "telegram-mcp": {
    "command": "npx",
    "args": ["-y","@chaindead/telegram-mcp"],
    "env": {
      "TG_APP_ID": "",
      "TG_API_HASH": ""
    }
  }
}
```

**Requires environment variables:** `TG_APP_ID`, `TG_API_HASH` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What chaindead/telegram-mcp MCP server does

The chaindead/telegram-mcp MCP server bridges Telegram account data and conversation actions to MCP-compatible AI applications. It belongs in the Communication category and is intended for workflows that need to inspect dialogs, review messages, update read status, or prepare responses from an assistant interface.

The available capabilities cover five operations:

- `tg_me` returns information about the current Telegram account.
- `tg_dialogs` lists dialogs, with an option to filter for unread conversations.
- `tg_read` marks a dialog as read.
- `tg_dialog` retrieves messages from a selected dialog.
- `tg_send` sends draft messages to a dialog.

These tools support tasks such as reviewing unread conversations, summarizing messages, identifying unanswered questions, and drafting replies.

## How it works

The chaindead/telegram-mcp MCP server runs as a local process and communicates with an MCP client. The client can then invoke the Telegram tools using natural-language requests. Telegram authentication is completed separately before normal tool use: obtain an API ID and API hash from Telegram, run the server's `auth` command with a phone number, and enter the verification code sent by Telegram.

Two authentication options are documented for specific situations. Add `--password` when the Telegram account uses two-factor authentication, and add `--new` to replace an existing session. Using the service also requires compliance with Telegram's API Terms of Service; misuse can lead to account suspension.

## Setup and configuration

The chaindead/telegram-mcp MCP server can be installed through Homebrew on macOS or Linux, run with the `@chaindead/telegram-mcp` NPX package on macOS, Linux, or Windows, downloaded as a platform release, or built with Go 1.24 or later. Source installation uses `go install`, and the README requires `GOBIN` to be available in `PATH`.

After authorization, configure the MCP client with the executable command and these environment values:

- `TG_APP_ID`: the Telegram application ID.
- `TG_API_HASH`: the Telegram application hash.
- `TG_SCHEMA_VERSION`: an optional schema-version override for clients with JSON Schema compatibility issues.

The documented Claude Desktop setup may also set `PATH` and `HOME`. NPX configuration uses `npx -y @chaindead/telegram-mcp` as the command and supplies the Telegram credentials in `env`.

The default schema is JSON Schema Draft 2020-12. Set `TG_SCHEMA_VERSION` or pass `--schema-version` to use another supported schema URL, such as Draft-07 for clients that reject Draft 2020-12.

## Tools and capabilities

Use `tg_dialogs` to identify unread conversations, then `tg_dialog` to retrieve their messages. `tg_read` lets an assistant update the read state after processing a dialog. `tg_send` handles draft message delivery to a selected dialog, while `tg_me` provides current-account context.

The README includes example workflows for monitoring a chat for topic updates, summarizing unread messages, suggesting chat organization, and preparing polite responses. The server does not document autonomous monitoring, scheduled execution, or automatic folder management.

## Limitations and notes

Telegram API credentials and an authenticated session are prerequisites. The server's use is subject to Telegram's API Terms of Service. Client compatibility may depend on JSON Schema support; VS Code is specifically cited as a client that may require the Draft-07 override. Claude Desktop and Cursor configuration examples are provided, and the README identifies Claude Desktop and Cursor as MCP applications that can connect to external tools.

_Full upstream README: https://allmcps.com/mcp/chaindead-telegram-mcp/readme_