mcp-telegram

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

Features

• Chat Management: List, search, mute/unmute chats, organize into folders

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

Related MCP server: Telegram MCP Server & Channel Monitor

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 api-id 123456789
mcp-telegram config set 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

29 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.

Server Variants

The server implements experimental server variants (SEP-2053): one server that offers several selectable capability sets. A client sends hints during initialize, the server ranks the variants, and the client picks one. Clients that don't understand the extension transparently get the full variant, so nothing changes for them.

Pin a single variant with --variant (or TELEGRAM_VARIANT) for clients that can't negotiate — e.g. --variant research exposes only the read-only subset:

mcp-telegram run --variant research

Leave it unset to expose all three and let the client choose.

Note on pinned-chat resources. In multi-variant mode (no --variant), pinned-chat resources are exposed on every variant and kept fresh by a single poller, but proactive resources/list_changed notifications are not delivered — the variants proxy can't forward the background watcher's notifications (an upstream library limitation). Clients pick up pin changes on their next resources/list. Pin a single --variant to restore live notifications.

Available Resources

Pinned chat resources are created dynamically for each pinned chat and refreshed in the background; clients receive resources/list_changed when the set changes (except in multi-variant mode — see the note under Server Variants).

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 api-id 123456789
mcp-telegram config set api-hash abcd1234

# List stored keys
mcp-telegram config list

# Delete a stored value
mcp-telegram config delete api-id

Allowed keys: api-id, api-hash, anthropic, gemini.

Credentials resolve in this priority order (higher wins): CLI flags (--api-id, --api-hash) → environment variables (including .env) → secure store values set via config set. This lets you keep stable values in the keychain and override per-run from the command line without editing the store.

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 proceeds automatically without a confirmation dialog.

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.

Note on the plaintext store (Linux/Windows): the session file grants full access to your Telegram account. Place it on an encrypted filesystem (LUKS/BitLocker) and do not sync ~/.local/state/mcp-telegram (or ~/.config) to an unencrypted cloud backup — a leaked session.json is equivalent to a leaked login.

Development

make build            # build the binary with version metadata
make lint             # golangci-lint
make test             # unit tests
make test-integration # end-to-end tests (need a real account + TEST_* vars)

Unit tests run without credentials. The integration suite in test/ is behind the integration build tag and drives the server over a real stdio pipe using a second MCP implementation (mark3labs/mcp-go) as the client, to catch wire-level interop issues. It reads the TEST_* variables documented in .env.example (e.g. TEST_CHAT_ID, TEST_GROUP_ID) and skips any test whose variable or Telegram credentials are unset.

License

MIT