telegram-mcp
An MCP server on top of a personal Telegram account — MTProto via teleproto, the maintained GramJS fork; not a bot. It lets an assistant read chats, send messages, run polls, and do most of what a regular Telegram client can.
Power your agent
การติดตั้งจากผู้เผยแพร่ ไม่ใช่เอนด์พอยต์ของ PlugMCP
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน 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.
เปิดจากผู้เผยแพร่
An MCP server on top of a personal Telegram account — MTProto via teleproto, the maintained GramJS fork; not a bot. It lets an assistant read chats, send messages, run polls, and do most of what a regular Telegram client can.
MCP server for a personal Telegram account: read chats, send messages, run polls
TypeScript with no build step: Node ≥ 22.18 runs .ts directly through type stripping, and types
are checked separately with npm run typecheck.
From npm, no clone needed:
npx @bstuff/telegram-mcp login # sign in by phone number; the session lands in ~/.telegram-mcp/session (mode 600)
npx @bstuff/telegram-mcp check # verify the stored session still works
Or from a checkout:
npm install
npm run login
npm run check
api_id / api_hash come from the environment, from .env in a checkout, or from
~/.telegram-mcp/.env (start from .env.example — this is the place when installed via npx).
The login command asks for them if neither is set.
These identify the application, not your account — every MTProto client needs its own pair. It takes about a minute:
Open https://my.telegram.org and enter your phone number in international format (+971…).
The confirmation code arrives inside Telegram, as a message from the official Telegram service account — not by SMS. Enter it on the page.
Click API development tools.
Fill in the form. Only App title and Short name are required; Short name must be 5–32
characters, letters and digits. Leave the URL empty and pick Desktop (or Other) as the
platform — none of this affects how the app works.
Press Create application. The page then shows App api_id (a number) and App api_hash
(32 hex characters).
Put both into .env:
cp .env.example .env
# TELEGRAM_API_ID=1234567
# TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
Worth knowing:
api_hash as a secret. It does not grant access to your account on its own, but Telegram
can ban an api_id that gets used for spam, and there is no way to delete an app once created.
.env is gitignored for that reason.my.telegram.org is unreachable from some networks. If the page will not load or the form
errors out on submit, try another network or browser — the site is noticeably flaky.Claude Code:
claude mcp add telegram -- npx -y @bstuff/telegram-mcp
# or, from a checkout:
claude mcp add telegram -- node ~/telegram-mcp/bin/telegram-mcp.ts
Or by hand, in the mcpServers block of any MCP client:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@bstuff/telegram-mcp"]
}
}
}
Two options. Through ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"telegram": {
"command": "npx",
"args": ["-y", "@bstuff/telegram-mcp"]
}
}
}
The app resolves bare commands against the login shell's PATH — its logs show npx being found
inside ~/.nvm/... — so an absolute path to Node is not required. A server configured this way
works, but gets no on/off switch in the UI.
The other option is an extension, which does get a switch in Settings → Extensions and in the chat tool list:
npm run bundle
This produces telegram.mcpb: a thin launcher that runs the server from this working copy. The
code is not copied into the bundle, so edits take effect after an app restart with no repack.
Install it via Settings → Extensions → Advanced settings → Extension Developer. The extension
settings expose "Read-only mode" and a timezone. Repack only when the tool list or the manifest
changes.
The extension icon comes from assets/icon-128.png and assets/icon-16.png; the script copies
them into the archive and fills in the manifest's icon and icons fields. To use your own,
drop in files with the same names and repack — if they are missing, the build simply produces no
icon.
The launcher checks the Node version and prints a readable error on an old runtime instead of a syntax error. To pin a specific binary instead of relying on PATH:
TELEGRAM_MCP_NODE=/opt/homebrew/bin/node npm run bundle
Do not keep both the config entry and the extension — the tools will show up twice.
Every tool accepts any of these in its chat field:
-1001234567890, 123456789@username or a https://t.me/username linkme — Saved MessagesTeam standup, baraholTitles are resolved against the dialog cache (the most recent TELEGRAM_MCP_DIALOG_LIMIT dialogs,
400 by default). If a fragment matches several chats, the server returns the candidates instead of
guessing.
Time fields (since, until, schedule_at) understand 7d, 36h, today, yesterday,
2026-07-17, 2026-07-17T10:00 and unix timestamps.
Prompts (slash commands in the client): catch_up, morning_telegram, run_poll.
What happened in "Team standup" this week? →
chat_digest+get_history
Start a poll in the work chat about when to do the retro: Tuesday, Wednesday, Thursday, multiple choice →
create_poll(multiple=true), thenpoll_results
Remind me about the call tomorrow at 9 →
send_message(chat="me", schedule_at="2026-08-10T09:00")
Who is on deploy duty today? →
random_member(chat="…", active_only=true)
bin/watch.ts (telegram-mcp watch when installed from npm) blocks until a matching message arrives, prints it, and exits. It is a CLI rather
than an MCP tool on purpose: an agent can run it in the background and be woken by the process
exit, the same way it waits on a CI run. No daemon or always-on process is involved.
node bin/watch.ts --chat "Team standup" --timeout 600
node bin/watch.ts --chat @somegroup --from @someone --contains "deployed"
node bin/watch.ts --to-me --timeout 1800 # mentions and replies to me, any chat
node bin/watch.ts --chat -1001234567890 --count 3 --json
Exit codes: 0 matched, 2 timed out, 1 error.
.env)src/client.ts connection, dialog cache, chat resolution
src/format.ts time parsing, message rendering, history collection
src/tools/*.ts tools by group: chats, read, write, media, polls, fun
bin/*.ts server entry point and interactive login
scripts/smoke.ts dev harness: drives the server over stdio like a real client
npm run typecheck
node scripts/smoke.ts '[["get_history",{"chat":"Team standup","since":"2d"}]]'
scripts/smoke.ts talks to the live account — clean up after any write calls.
~/.telegram-mcp/session with
mode 600 and must never reach git (.gitignore already covers it).instructions.delete_messages and close_poll cannot be undone.TELEGRAM_MCP_READ_ONLY=1.The code is MIT.
This is an independent project. It is not affiliated with, endorsed by, or supported by Telegram FZ-LLC or Telegram Messenger Inc. "Telegram" is their trademark, used here nominatively to say what this server talks to.
The logo in assets/icon-128.png and assets/icon-16.png comes from telegram.org and belongs to
its owner. It is included solely as the extension icon and is not covered by the MIT license.
If that is inconvenient, delete the files — npm run bundle works fine without them — or replace
them with your own using the same names.
MCP server for a personal Telegram account: read chats, send messages, run polls
เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Telegram ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-10-28 MCP server for a personal Telegram account: read chats, send messages, run polls