The server is a bridge between the Telegram API and the AI assistants and is based on the Model Context Protocol.

• What is MCP?
• What does this server do?
  • Capabilities
  • Prompt examples
    • Message Management
    • Organization
    • Communication
• Installation
  • Homebrew
  • NPX
  • From Releases
    • MacOS
    • Linux
    • Windows
  • From Source
• Configuration
  • Authorization
  • Client Configuration
• Star History

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.

• 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)

Here are some example prompts you can use with AI assistants:

• "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"

• "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"

• "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"

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

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

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

• Claude MCP server 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 and Client Configuration.

# 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

# 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

# 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

# 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

Requirements:

• Go 1.24 or later
• GOBIN in PATH

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

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.

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:

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