mcp-telegram

MCP server for Telegram — let AI assistants interact with your Telegram account

Features

• Chat Management: List, search, mute/unmute chats

• Messages: Read, search, inspect context, send, draft, schedule, link-resolve, 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
make

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

Store credentials (macOS Keychain; plaintext JSON at ~/.local/state/mcp-telegram/config.json with 0600 perms on Linux/Windows):

mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234efgh5678

Or use a .env file:

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

claude mcp add telegram -- /path/to/mcp-telegram run

Set environment variables in your .env file or pass them via --env.

Available Tools

19 tools exposed to MCP clients. Messages are identified by opaque string handles ("42" for regular, "s:42" for scheduled) — copy them back verbatim from tool outputs to follow-up calls, never parse or construct them manually.

Available Resources

Pinned chat resources are created dynamically for each pinned chat and refreshed in the background; clients will receive resources/list_changed when the set changes.

Available Prompts

3 parameterized prompts that MCP clients expose as slash-commands or quick actions.

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"

• "Find messages mentioning 'invoice' in my work chat from last week"

• "Open the context around this Telegram link: https://t.me/example/123"

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"

• "Resolve this Telegram message link and show me the thread context"

Backup & Export

• "Backup my conversation with [contact] to a file"

• "Export the last week of messages from [group]"

• "Backup media-only updates too so nothing is silently skipped"

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

# Securely store config values (macOS Keychain / file on Linux)
mcp-telegram config set TELEGRAM_API_ID 123456789
mcp-telegram config set TELEGRAM_API_HASH abcd1234

# List stored keys
mcp-telegram config list

# Delete a stored value
mcp-telegram config delete TELEGRAM_API_ID

Allowed keys: TELEGRAM_API_ID, TELEGRAM_API_HASH, ANTHROPIC_API_KEY, GEMINI_API_KEY.

Configuration Options

Destructive Actions

Tools like DeleteMessage request user confirmation via MCP elicitation before proceeding. If your MCP client does not support elicitation, the server relies on the LLM's instructions to confirm verbally before executing destructive operations.

Session Storage

• macOS: Stored securely in Keychain.

• Linux/Windows: Stored in ~/.local/state/mcp-telegram/session.json with 0600 file permissions. The file is plaintext — keep the containing user account trusted, and prefer running on macOS when handling sensitive accounts.

Config values set via mcp-telegram config set (API keys, Telegram credentials) follow the same backend: Keychain on macOS, plaintext JSON on Linux/Windows.

License

MIT