Log inSubmit server
Telegram MCP logo

Telegram MCP

by chaindead

Connects AI assistants to Telegram for account data, dialogs, messages, read status, and draft replies.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Telegram MCP

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "chaindead-telegram-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@chaindead/telegram-mcp"
      ],
      "env": {
        "TG_APP_ID": "YOUR_VALUE_HERE",
        "TG_API_HASH": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y @chaindead/telegram-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 24d ago.

Overview

The chaindead/telegram-mcp MCP server connects AI assistants to the Telegram API through Model Context Protocol. It exposes tools for account details, dialog lists, message retrieval, read status updates, and draft message sending. Install it with a release binary, Homebrew, NPX, or Go, then authorize a Telegram API session. Reach for it when an assistant needs to inspect or organize Telegram conversations through supported MCP clients.

Use cases

  • Review unread Telegram dialogs
  • Summarize messages from selected chats
  • Draft replies to Telegram conversations
  • Mark processed dialogs as read
  • Inspect current Telegram account details

Key features

  • Retrieve current account information
  • List dialogs with unread filtering
  • Fetch messages from a dialog
  • Mark dialogs as read
  • Send draft messages
  • Override the JSON Schema version

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 1d ago

Recent health check succeeded.

20/20 checks healthy over the last 78d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 9d ago via OSV.dev · @chaindead/telegram-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars349Stargazers on the source repository.
npm downloads2.7kPackage downloads in the last 30 days.
Last commit5mo agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How Telegram MCP works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Telegram MCP

chaindead/telegram-mcp is an MCP server that connects AI assistants to the Telegram API. Its main tools return account information, list dialogs, retrieve messages, mark dialogs as read, and send draft messages. It supports Telegram conversation workflows through MCP clients such as Claude Desktop and Cursor after account authorization.

Install it with Homebrew, NPX, a platform release binary, or Go. Homebrew supports macOS and Linux, while NPX supports macOS, Linux, and Windows. Source installation requires Go 1.24 or later; the documented command is `go install github.com/chaindead/telegram-mcp@latest`.

Authenticate it with the `auth` command using a Telegram API ID, API hash, and phone number. Run `telegram-mcp auth --app-id <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>`, then enter Telegram's verification code. Add `--password` for 2FA or `--new` to replace an existing session.

Yes, Cursor is supported through a standard MCP configuration using the `telegram-mcp` command and the `TG_APP_ID` and `TG_API_HASH` environment variables. The README provides a Cursor configuration example for connecting the server.

Set `TG_SCHEMA_VERSION` or pass `--schema-version` to select a compatible JSON Schema URL. The default is Draft 2020-12; the README recommends Draft-07 for clients such as VS Code that do not support Draft 2020-12.

Related MCP servers

All in Communication All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewTelegram MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/chaindead-telegram-mcp?style=directory)](https://allmcps.com/mcp/chaindead-telegram-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/chaindead-telegram-mcp"><img src="https://allmcps.com/api/badge/chaindead-telegram-mcp?style=directory" alt="Telegram MCP on AllMCPs" /></a>