Features

• Chat Management: List, search, mute/unmute chats
• Messages: Read, send, draft, schedule, and backup messages
• AI Summarization: Summarize chat conversations using multiple LLM providers
• Secure: Session stored in macOS Keychain (file-based storage on Linux/Windows)

Installation

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

Or build from source:

git clone https://github.com/tolmachov/mcp-telegram.git
cd mcp-telegram
go build -o mcp-telegram .

Setup

1. Get Telegram API Credentials

1. Go to my.telegram.org/apps
2. Create an application
3. Copy api_id and api_hash

2. Configure Environment

cp .env.example .env
# Edit .env with your credentials

3. Login to Telegram

mcp-telegram login --phone +1234567890

You'll be prompted for a verification code sent to your Telegram.

4. Configure MCP Client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "telegram": {
      "command": "mcp-telegram",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "tg": {
      "type": "stdio",
      "command": "/path/to/mcp-telegram",
      "args": ["run"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash"
      }
    }
  }
}

Available Tools

Available Resources

Pinned chat resources are created dynamically for each pinned chat and updated on every resources/list request.

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"

Backup & Export

• "Backup my conversation with [contact] to a file"
• "Export the last week of messages from [group]"

Chat Summarization

The SummarizeChat tool supports multiple LLM providers:

• sampling (experimental): Uses the MCP client's LLM via MCP Sampling. Only works with clients that support sampling: VS Code, fast-agent, Continue. Does NOT work with Claude Desktop or Claude Code.
• ollama: Local LLM via Ollama - no API key required
• gemini: Google Gemini API
• anthropic: Anthropic Claude API

Configure via environment variables:

SUMMARIZE_PROVIDER=ollama  # or: sampling, gemini, anthropic
SUMMARIZE_MODEL=           # provider-specific model name

Commands

# Run MCP server (used by MCP clients)
mcp-telegram run

# Login to Telegram
mcp-telegram login --phone +1234567890

# Logout and delete session
mcp-telegram logout

Configuration Options

Session Storage

• macOS: Stored securely in Keychain
• Linux/Windows: Stored in ~/.local/state/mcp-telegram/session.json

License

MIT