tg_meLABSCO SUMMARY
Telegram becomes readable without a bot account.
Running on the User API means it sees what you see, including the private chats a bot could never join. The per-tool permissions and the chat whitelist are the counterweight: read, send, draft and mark-read are separate grants, so an assistant can be allowed to catch you up without being allowed to reply.
What it is
A Go MCP server that connects to a real Telegram account over the User API (MTProto) rather than as a bot. Each tool sits behind a named permission, and the chats it can see are limited by an access whitelist.
What you get
- Dialogs listed, limited to the chats the whitelist allows
- Message history fetched with pagination, date filtering and media download
- Messages searched inside a chat by text, with an optional sender filter
- Text or a file sent, with an optional reply-to
- Messages forwarded from one chat to another
- A draft saved without sending it
- A chat marked read
- Typed peer references and lazy peer resolution, which is what keeps rate-limit waits out of startup
Requirements
Your own api_id and api_hash from my.telegram.org, and Go 1.26 or newer. Telegram's API terms govern use of the User API, and the account it acts as is your own.
Setup effort
Follow the published steps — go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest
USE CASES
01
Catching up on what you missed
List the dialogs the whitelist exposes, then pull history for the ones that matter, filtered to the days you were away.
02
Finding a message you know exists
Search inside the chat by text, narrowing by sender when several people were talking, then read the surrounding history for context.
03
Replying without switching apps
Read the thread, then send the reply against the specific message so it lands threaded rather than loose at the bottom.
04
Preparing a reply for you to approve
Save the answer as a draft instead of sending it. It waits in the chat until you open Telegram and press send yourself.
05
Passing something along to another chat
Forward the messages rather than retyping them, so attribution and attachments survive the move.
06
Clearing the unread count once you have read it
Mark the chat read after the catch-up, so the unread badge reflects what you actually know.
8 tools
Listed in project docs. Your client may show a different list.
tg_dialogstg_historytg_searchtg_sendtg_forwardtg_drafttg_mark_readBEFORE YOU INSTALL
What to know first
Tools you get
8 tools named in the project's documentation.
Requires
- Go 1.26+
- A Telegram account
- TG_APP_ID in your environment
- TG_API_HASH in your environment
Where it runs
All 3 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
go install github.com/Prgebish/mcp-telegram/cmd/mcp-telegram@latest
export TG_APP_ID=12345
export TG_API_HASH="<YOUR_TG_API_HASH>"
mcp-telegram auth --config config.yamlMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add telegram -- <YOUR_PATH_TO_MCP_TELEGRAM> serve --config <YOUR_PATH_TO_CONFIG><YOUR_PATH_TO_MCP_TELEGRAM> is the full path of the installed binary — go install puts it in $(go env GOPATH)/bin, usually ~/go/bin —, and <YOUR_PATH_TO_CONFIG> is the full path of the config.yaml you created. This command passes no TG_APP_ID or TG_API_HASH, so export them in the shell you start Claude Code from.
Before the auth step, create config.yaml: under telegram set app_id: ${TG_APP_ID}, api_hash: ${TG_API_HASH} and session_path; under acl.chats list each chat the server may touch (@username, user:ID, chat:ID or channel:ID) with its permissions (read, send, draft, mark_read). The ACL is default-deny, so a chat you do not list is invisible. Get api_id and api_hash from my.telegram.org.
Claude Desktop, Cursor
JSON
{
"mcpServers": {
"telegram": {
"command": "<YOUR_PATH_TO_MCP_TELEGRAM>",
"args": [
"serve",
"--config",
"<YOUR_PATH_TO_CONFIG>"
],
"env": {
"TG_APP_ID": "12345",
"TG_API_HASH": "<YOUR_TG_API_HASH>"
}
}
}
}<YOUR_PATH_TO_MCP_TELEGRAM> is the full path of the installed binary — go install puts it in $(go env GOPATH)/bin, usually ~/go/bin —, and <YOUR_PATH_TO_CONFIG> is the full path of the config.yaml you created. TG_APP_ID and TG_API_HASH are your Telegram api_id and api_hash.
Before the auth step, create config.yaml: under telegram set app_id: ${TG_APP_ID}, api_hash: ${TG_API_HASH} and session_path; under acl.chats list each chat the server may touch (@username, user:ID, chat:ID or channel:ID) with its permissions (read, send, draft, mark_read). The ACL is default-deny, so a chat you do not list is invisible. Get api_id and api_hash from my.telegram.org.
