telegram-mcp

MIT License
38
  • Apple
  • Linux

Integrations

  • Provides a bridge to the Telegram API, allowing retrieval of user data, listing of dialogs (chats, channels, groups), and access to messages within those dialogs.

Telegram MCP server

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.

Table of Contents

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:

npx -y @chaindead/telegram-mcp auth ...
{ "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
Windows
  1. Download the latest release for your architecture:
  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
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
  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

    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 configurationfor 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>" } } } }

Star History

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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

  1. Table of Contents
    1. What is MCP?
      1. What does this server do?
        1. Capabilities
        2. Prompt examples
      2. Installation
        1. Homebrew
        2. NPX
        3. From Releases
        4. From Source
      3. Configuration
        1. Authorization
        2. Client Configuration
      4. Star History

        Related MCP Servers

        • A
          security
          A
          license
          A
          quality
          A bridge allowing Claude Desktop to access Telegram chats and messages via the Model Context Protocol, providing read-only capabilities to retrieve dialogs and messages from Telegram.
          Last updated -
          2
          38
          Python
          MIT License
          • Apple
        • A
          security
          A
          license
          A
          quality
          Enables AI models to interact with messages from various messaging platforms (Mobile, Mail, WhatsApp, LinkedIn, Slack, Twitter, Telegram, Instagram, Messenger) through a standardized interface.
          Last updated -
          3
          3
          Python
          MIT License
          • Linux
        • -
          security
          A
          license
          -
          quality
          A Model Context Protocol server that enables AI assistants to interact with Telegram, allowing them to search channels, list available channels, retrieve messages, and filter messages by regex patterns.
          Last updated -
          12
          JavaScript
          MIT License
          • Apple
        • -
          security
          A
          license
          -
          quality
          A server that enables interaction with Telegram chats directly through MCP-compatible hosts like Claude for Desktop, providing tools to retrieve chats, get messages, and send messages.
          Last updated -
          85
          Python
          Apache 2.0
          • Apple
          • Linux

        View all related MCP servers

        ID: evp8xtmfsy