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.
Potencialize seu agente
Instalação do publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
Ainda não há uma versão empacotada no registro. Siga o README do repositório.
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
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)
Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Este registro não lista nenhuma variável de ambiente obrigatória.
MCP Telegram roda localmente via stdio.
Última verificação: 2026-10-28. MCP server for Telegram — connect Claude to your real Telegram account via User API (MTProto)