telegram-mcp
Telegram MCP for managing dialogs, messages, drafts, read statuses, and more.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/chaindead--telegram-mcp)HTML
<a href="/listings/chaindead--telegram-mcp"><img src="/api/listings/chaindead--telegram-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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](#authorization) becomes:
npx -y @chaindead/telegram-mcp auth ...
- [Claude MCP server configuration](#client-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](#authorization) and [Client Configuration](#client-configuration).
From Releases
MacOS
<details>
> **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
</details>
Linux
<details>
> **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
</details>
Windows
<details>
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 </details>
From Source
Requirements: - Go 1.24 or later - GOBIN in PATH
go install github.com/chaindead/telegram-mcp@latest
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 285 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- [](https://github.com/punkpeye/awesome-mcp-servers?tab=readme-ov-file#communication)
- [](https://github.com/chaindead/telegram-mcp?tab=readme-ov-file#installation)
- [](https://opensource.org/licenses/MIT)
- [](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)
- - [JSON Schema Version](#json-schema-version)
- - [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": "<your-api-id>",
- "TG_API_HASH": "<your-api-hash>"
- }
- }
- }
- }
- ```
- For complete setup instructions, see [Authorization](#authorization) and [Client Configuration](#client-configuration).
- ### From Releases
- #### MacOS
- <details>
- > **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
- ```
- </details>
- #### Linux
- <details>
- > **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
- ```
- </details>
- #### Windows
- <details>
- #### 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
- </details>
- ### 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 <your-api-id> --api-hash <your-api-hash> --phone <your-phone-number>
- ```
- 📩 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": "<your-app-id>",
- "TG_API_HASH": "<your-api-hash>",
- "PATH": "<path_to_telegram-mcp_binary_dir>",
- "HOME": "<path_to_your_home_directory"
- }
- }
- }
- }
- ```
- for Cursor:
- ```json
- {
- "mcpServers": {
- "telegram-mcp": {
- "command": "telegram-mcp",
- "env": {
- "TG_APP_ID": "<your-app-id>",
- "TG_API_HASH": "<your-api-hash>"
- }
- }
- }
- }
- ```
- ### JSON Schema Version
- Some MCP clients (e.g. VS Code) do not support JSON Schema Draft 2020-12 and will reject tools that use it. You can override the JSON Schema version by setting the `--schema-version` flag or the `TG_SCHEMA_VERSION` environment variable.
- Common values:
- | Version | URL |
- |---------|-----|
- | Draft-07 (recommended for VS Code) | `https://json-schema.org/draft-07/schema#` |
- | Draft 2020-12 (default) | `https://json-schema.org/draft/2020-12/schema` |
- ## Star History
- <a href="https://www.star-history.com/#chaindead/telegram-mcp&Date">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=chaindead/telegram-mcp&type=Date&theme=dark" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=chaindead/telegram-mcp&type=Date" />
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=chaindead/telegram-mcp&type=Date" />
- </picture>
- </a>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.