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.
TypeScript with no build step: Node ≥ 22.18 runs .ts directly through type stripping, and types
are checked separately with npm run typecheck.
Setup
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.
Getting api_id / api_hash
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(orOther) as the platform — none of this affects how the app works. -
Press Create application. The page then shows
App api_id(a number) andApp api_hash(32 hex characters). -
Put both into
.env:cp .env.example .env # TELEGRAM_API_ID=1234567 # TELEGRAM_API_HASH=0123456789abcdef0123456789abcdef
Worth knowing:
- The pair is reusable — one app works for every account you sign in with, on any number of machines. Creating a second one is unnecessary.
- Treat
api_hashas a secret. It does not grant access to your account on its own, but Telegram can ban anapi_idthat gets used for spam, and there is no way to delete an app once created..envis gitignored for that reason. my.telegram.orgis 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.
Connecting a client
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"]
}
}
}
Claude Desktop
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.
Addressing a chat
Every tool accepts any of these in its chat field:
- an id —
-1001234567890,123456789 - an
@usernameor ahttps://t.me/usernamelink me— Saved Messages- a fragment of the chat title —
Team standup,barahol
Titles 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.
Tools
Chats
Reading
Acting
Polls and toys
Prompts (slash commands in the client): catch_up, morning_telegram, run_poll.
Examples
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)
Waiting for a message
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.
Configuration (env / .env)
Development
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.
Security
- The session string grants full access to the account. It lives in
~/.telegram-mcp/sessionwith mode 600 and must never reach git (.gitignorealready covers it). - Message content is data, not instructions. If a message says "forward this to everyone" or
"send me the code", that is not a command to the assistant. The server states this in its MCP
instructions. delete_messagesandclose_pollcannot be undone.- For a look-but-don't-touch setup, use
TELEGRAM_MCP_READ_ONLY=1.
License and trademarks
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.