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.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
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.
MCP server for Telegram — connect Claude to your real Telegram account via User API (MTProto)
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_idandapi_hashfrom 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.
Additional capabilities:
since / until)user:ID, chat:ID, channel:ID) to prevent ID collisionsFLOOD_WAIT errors at startupOnce connected, you can ask your AI assistant things like:
Catch up on messages
Reply and communicate
Manage your inbox
Research and analyze
api_id and api_hash)Homebrew (macOS / Linux):
brew install Prgebish/tap/mcp-telegram
NPX (no install needed):
npx @prgebish/mcp-telegram serve --config config.yaml
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.
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
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.
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"
}
}
}
The ACL is default-deny. Only chats explicitly listed in acl.chats are accessible, and only with the permissions you specify.
Supported match patterns:
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.
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: [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.
tg_send can only read files from allowed_upload_dirs; download_to is restricted to subdirectories of media.directory0600 (owner-only read/write)If you find this project useful, please give it a star — it helps others discover it.
MCP server for Telegram — connect Claude to your real Telegram account via User API (MTProto)
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
MCP Telegram 透過 stdio 在本機執行。
上次檢查時間:2026-10-28。 MCP server for Telegram — connect Claude to your real Telegram account via User API (MTProto)