mcp-telegram

An MCP server that connects AI assistants like Claude to your real Telegram account via the User API (MTProto). Not a bot — Claude reads and sends messages as you.

Built with gotd/td and the official MCP Go SDK.

Telegram API Terms of Service: This project uses the Telegram User API. You must obtain your own api_id and api_hash from my.telegram.org and comply with the Telegram API Terms of Service. Misuse of the User API (spam, bulk messaging, scraping) may result in your account being banned. You are solely responsible for how you use this tool.

Contents

• Features
• What you can do with it
• How it compares to chaindead/telegram-mcp
• Quick start
• Client configuration
• Configuration reference
• Security

Features

| Tool | What it does | Required permission | |------|-------------|---------------------| | tg_me | Returns current account info | — | | tg_dialogs | Lists dialogs visible to the ACL whitelist | — | | tg_history | Fetches message history with pagination, date filtering, and media download | read | | tg_search | Searches messages in a chat by text query, with optional sender filter | read | | tg_send | Sends a text message or file, with optional reply-to | send | | tg_forward | Forwards messages from one chat to another | read + send | | tg_draft | Saves a draft message (does not send) | draft | | tg_mark_read | Marks a chat as read | mark_read |

Additional capabilities:

• File and photo sending
• Forward messages between chats
• Reply to specific messages
• Download photos and documents from message history
• Filter history by date range (since / until)
• Typed peer references (user:ID, chat:ID, channel:ID) to prevent ID collisions
• Lazy peer resolution — avoids FLOOD_WAIT errors at startup
• Global rate limiting at the RPC level

What you can do with it

Once connected, you can ask your AI assistant things like:

Catch up on messages

• "Check my unread Telegram messages and give me a summary"
• "What did @alice write in the last 24 hours?"
• "Show me messages from the Dev Team chat since Monday"

Reply and communicate

• "Draft a response to the last message from @bob — don't send it yet"
• "Send 'sounds good, let's meet at 3pm' to @alice"
• "Reply to message 1234 in the project chat with my feedback"

Manage your inbox

• "Mark all read in the news channel"
• "Which of my whitelisted chats have unread messages?"
• "Download the photos from today's messages in the design chat"

Research and analyze

• "Find all messages mentioning the deployment in the last week"
• "Summarize the discussion in the team chat from yesterday"
• "What files were shared in the project channel this month?"

How it compares to chaindead/telegram-mcp

| | mcp-telegram | chaindead/telegram-mcp | |---|---|---| | Access control | Default-deny ACL whitelist with granular per-chat permissions | Full access to all chats | | Peer addressing | Typed references (user:ID, chat:ID, channel:ID) | Numeric IDs only (collision-prone) | | Configuration | YAML config with environment variable expansion | CLI flags | | Startup safety | Lazy peer resolution (no bulk API calls) | Eager resolution (FLOOD_WAIT risk) | | Rate limiting | Built-in token bucket middleware | None | | File support | Send files, photos; download media from history | Text only | | Reply support | Yes | No | | Date filtering | Yes | No |

Quick start

Prerequisites

• Go 1.26+
• A Telegram account
• API credentials from my.telegram.org (api_id and api_hash)

Install

Homebrew (macOS / Linux):

brew install Prgebish/tap/mcp-telegram

Pre-built binaries (macOS / Linux / Windows):

Download from GitHub Releases.

Go install:

go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest

From source:

git clone https://github.com/Prgebish/mcp-telegram.git
cd mcp-telegram
go build ./cmd/mcp-telegram

This produces mcp-telegram (or mcp-telegram.exe on Windows) in the current directory.

Authenticate

Run the auth command once to create a session file. You will be prompted for your phone number, the login code, and (if enabled) your 2FA password.

macOS / Linux:

export TG_APP_ID=12345
export TG_API_HASH="your_api_hash"

mcp-telegram auth --config config.yaml

Windows (PowerShell):

$env:TG_APP_ID = "12345"
$env:TG_API_HASH = "your_api_hash"

mcp-telegram.exe auth --config config.yaml

Windows (cmd):

set TG_APP_ID=12345
set TG_API_HASH=your_api_hash

mcp-telegram.exe auth --config config.yaml

Configure

Create a config.yaml:

telegram:
  app_id: ${TG_APP_ID}
  api_hash: ${TG_API_HASH}
  session_path: ~/.config/mcp-telegram/session.json

acl:
  chats:
    - match: "@username"
      permissions: [read, draft, mark_read]
    - match: "user:123456789"
      permissions: [read, send]
    - match: "channel:2225853048"
      permissions: [read, mark_read]

limits:
  max_messages_per_request: 50
  max_dialogs_per_request: 100
  rate:
    requests_per_second: 2.0
    burst: 3

logging:
  level: info

Environment variables in ${...} syntax are expanded at load time.

Client configuration

The server communicates over stdio — your MCP client starts and manages the process.

Claude Code (CLI — add via command):

claude mcp add telegram -- /path/to/mcp-telegram serve --config /path/to/config.yaml

Claude Desktop / Claude Code (~/.claude.json or claude_desktop_config.json):

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/mcp-telegram",
      "args": ["serve", "--config", "/path/to/config.yaml"],
      "env": {
        "TG_APP_ID": "12345",
        "TG_API_HASH": "your_api_hash"
      }
    }
  }
}

Cursor (Settings > MCP Servers > Add):

{
  "telegram": {
    "command": "/path/to/mcp-telegram",
    "args": ["serve", "--config", "/path/to/config.yaml"],
    "env": {
      "TG_APP_ID": "12345",
      "TG_API_HASH": "your_api_hash"
    }
  }
}

Configuration

ACL

The ACL is default-deny. Only chats explicitly listed in acl.chats are accessible, and only with the permissions you specify.

Supported match patterns:

| Pattern | Example | Description | |---------|---------|-------------| | @username | @johndoe | Match by Telegram username (case-insensitive) | | +phone | +79001234567 | Match by phone number | | user:ID | user:123456789 | Match a user by numeric ID | | chat:ID | chat:987654321 | Match a group chat by numeric ID | | channel:ID | channel:2225853048 | Match a channel or supergroup by numeric ID |

Permission types: read, send, draft, mark_read.

If the same peer matches multiple rules (e.g. via @username and user:ID), permissions are merged — they never shadow each other.

Rate limiting

The limits.rate section configures a global token bucket that wraps all Telegram RPC calls:

• requests_per_second — sustained rate (default: 2.0)
• burst — maximum burst size (default: 3)

Media download

media:
  download: [photo, document, video, voice, audio]
  directory: ~/telegram-media
  allowed_upload_dirs:
    - ~/Documents
    - ~/Downloads

When configured, tg_history will automatically download media files to the specified directory. The download_to parameter can override the path, but only to media.directory or its subdirectories.

allowed_upload_dirs restricts which directories tg_send can read files from. File sending is disabled unless this is configured.

Security

• Default-deny ACL — no chat is accessible unless explicitly whitelisted
• Filesystem boundary — tg_send can only read files from allowed_upload_dirs; download_to is restricted to subdirectories of media.directory
• Session file permissions — enforced to 0600 (owner-only read/write)
• No secret logging — API hashes, session tokens, and auth keys are never written to logs
• No access hash exposure — internal Telegram access hashes are stripped from all tool output
• Rate limiting — prevents accidental API abuse
• Local timezone — date filters use your system timezone, not UTC

License

MIT

If you find this project useful, please give it a star — it helps others discover it.