telegram-mcp
Connects an assistant to a Telegram bot, enabling it to message the user, send files, ask questions with answer buttons, read incoming messages, search connected groups and forum topics, and optionally read and reply in personal chats according to Telegram Business permissions.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
telegram-mcp
A remote MCP server that connects your AI assistant — Claude, ChatGPT, Codex or any MCP client — to you through a Telegram bot. The assistant can:
message you when it finishes or gets stuck ("ping me in Telegram when the build is done"),
send files it built (reports, archives, screenshots, up to 50 MB) without base64 through the model,
ask you something and wait, with answer buttons ("ask me in Telegram before deploying"),
read what you send the bot ("I sent you a file in Telegram, take a look"),
read groups you connect: search by keywords, find every message where someone tagged the bot, follow replies and walk the messages around them for context, work inside forum topics,
answer where the bot is not a member: tag it in any chat (Telegram's guest mode) and your assistant answers there,
show more than text: rich messages with tables and collapsible blocks, coloured buttons, quizzes, live previews of a long answer, interactive widgets,
read your personal chats, if you connect the bot to your account ("what did Anna write yesterday?"), and reply in them as you — only if you allowed that in Telegram.
It runs on Cloudflare Workers with D1. Each person who connects sees only their own private chat with the bot, the groups they connected and their own personal chats.
What the bot can read is only what it received. The Bot API has no history, so the bot stores what Telegram delivers to it, for 14 days (
RETENTION_DAYS), and deletes the rest. Nothing from before the bot joined a chat, nothing from your other chats, and in groups only what privacy mode lets through. The model is told this, so it does not mistake "not stored" for "never happened".
Setup
1. Create the bot
In @BotFather: /newbot, and keep the token.
2. Deploy
The button asks for BOT_TOKEN (required) and ALLOWED_USER_IDS (optional, see below), creates
the D1 database, and deploys. The Worker creates its own tables on first use.
bun installbunx wrangler loginbun run deploybunx wrangler secret put BOT_TOKEN3. Finish in BotFather
Open https://telegram-mcp.<your-subdomain>.workers.dev in a browser. The page registers the
bot's webhook and shows what is left to do:
/setdomain→ your bot →telegram-mcp.<your-subdomain>.workers.dev. Telegram Login only works on this domain.Bot Settings (in BotFather's Mini App) → Guest Mode → on, if you want to call your assistant from chats the bot is not in (see Answering from Telegram).
/setprivacy→ your bot → Disable, if the bot should see every message in groups. With privacy on it only sees commands, @mentions and replies to it (an admin bot sees everything either way). Telegram applies the change only to groups the bot joins afterwards, so re-add it to groups it is already in.
4. Lock it to yourself (optional)
By default anyone may connect their own Telegram account to your deployment. Each person still sees only their own chat and groups, but to keep it to yourself:
Send
/startto your bot. Its menu shows your Telegram ID (or ask @userinfobot).Set
ALLOWED_USER_IDSto that number (comma-separate several):bunx wrangler secret put ALLOWED_USER_IDS, or in the Cloudflare dashboard → Worker → Settings → Variables and Secrets.
Others then get "this bot is private" with their ID, and a group added by someone not on the list is left at once.
5. Connect your assistant
Claude (web, desktop, mobile): Settings → Connectors → Add custom connector → URL
https://telegram-mcp.<your-subdomain>.workers.dev/. Leave the OAuth fields empty. Claude opens
Telegram's login page; confirm, allow the bot to message you, and you are back in Claude.
Claude Code:
claude mcp add --transport http telegram https://telegram-mcp.<your-subdomain>.workers.dev/Then /mcp in Claude Code to sign in.
ChatGPT (needs Developer mode: Pro, Business, Enterprise, Edu): Settings → Apps & Connectors → Advanced → Developer mode on, then Create with the same URL and OAuth authentication. ChatGPT registers itself; no client id needed.
Codex:
codex mcp add telegram --url https://telegram-mcp.<your-subdomain>.workers.dev/codex mcp login telegramOn the machine that runs the relay for Codex (below) this is not needed: each run gets its own
sign-in there, under a server name of the relay's (tg_relay), and your own telegram stays as it
is.
Related MCP server: Telegram MCP Server
Groups
Adding the bot to a group gives you (whoever added it) access straight away. The menu's Connect a group button opens Telegram's own picker for that.
Anyone else in the group links their own assistant by sending
/connectin the group.Two people, one group: access is per person. Each connects and revokes on their own; messages are stored once.
History for later connectors: someone who connects after the bot joined sees the stored history only if the group shows history to new members, which the bot can only check as an admin. Otherwise they see messages from the moment they connect, and the bot says which applies.
Groups in the menu (or
/groups) lists your groups; revoke any of them there. When the last person revokes a group, its stored history is deleted.Leaving a group drops your access: the bot notices the leave when Telegram tells it (always as an admin, otherwise unless the group hides join and leave messages), and re-checks membership at least hourly before reading a group anyway.
Forum topics are kept apart: messages carry their topic,
list_chatsnames the topics, and the assistant can read or post within one.Replies: when someone replies to a message, the bot keeps the original too (even one older than the bot), so "@bot what about this?" under a message shows the assistant both.
Bot commands: /start opens the menu (groups, connecting a group, personal chats, scenes, how it
works, your Telegram ID). /connect in a group, /groups and /disconnect (signs out every assistant
connected with your account) work too; only /start is listed in Telegram's command suggestions.
Personal chats
Telegram lets a user connect a bot to their own account (Telegram Business → Chatbots). The bot then receives the user's private chats with other people, and your assistant can read and search them like any other chat.
In @BotFather: your bot → Bot Settings → Secretary Mode → on (called Business Mode before). Once per bot.
Each user who wants it, in Telegram: Settings → Telegram Business → Chatbots → add the bot. There they choose which chats it gets (all except some, or only some) and what it may do.
What your assistant may do is exactly what you allowed there, checked on every call:
Permission in Telegram | What it lets the assistant do |
(connected at all) | read and search the chats you gave it |
Reply to messages |
|
Mark messages as read |
|
Delete sent messages |
|
Without a permission the tool refuses before anything reaches Telegram. Change it in Telegram and
the next call follows; the bot tells you in its chat what your assistant can do whenever it changes.
Telegram also allows writing only within 24 hours of the other person's last message. Buttons,
ask_user, reactions, pins, forwards, albums, locations and polls are not used in personal chats. The assistant is told that
anything it sends there goes out as you, and to send only when you ask it to in the conversation.
Acting as you has its own tools, marked destructive, and the bot's tools (send_message,
edit_message, …) refuse personal chats. So your client can let the assistant message you and your groups
freely and still ask you before anything goes out in your name: in Claude Code, allow
mcp__Telegram and add mcp__Telegram__send_as_user, …__edit_as_user, …__delete_as_user and
…__mark_read to permissions.ask.
What the bot sees: messages from the moment you connect it, in the chats you chose, including your own replies. No history, no secret chats, no groups.
Removing the bot there deletes everything it stored from your personal chats. Storage starts only once you have also signed an assistant in.
Other people's privacy: the people you talk to have not agreed to anything. Their messages sit in the database for
RETENTION_DAYS, readable by whoever runs the Worker. Give the bot only the chats you need, and run your own deployment.Cost: every message in a connected chat is a Worker request and about two D1 row writes, like a busy group. With
ALLOWED_USER_IDSempty, anyone can connect their account to your bot on your quota.
Files
Models cannot attach files to MCP calls, so files travel through short-lived links instead:
Sending:
create_upload_urlreturns a one-time link (10 minutes). Claude Code, or any agent with a shell, runscurl -T file '<link>', and the Worker passes the file straight to Telegram. Nothing is stored. Up to 50 MB (photos 10 MB), which is Telegram's limit for bots.Without a shell (claude.ai chat, ChatGPT):
send_filetakes text, or base64 up to 1 MB. In claude.ai the code sandbox can use the curl route too, if network access to your Worker's domain is allowed in Claude's settings.Receiving:
get_filereturns a 15-minute download link, plus the content itself for images up to 1.5 MB and the start of text files (up to ~60k characters). Telegram lets bots download files up to 20 MB.
Upload links stream the body straight on to Telegram (the Worker never holds the file), so curl must
send the size — curl -T does. Links stop working after /disconnect or when your ID leaves the
allowlist.
Tools
Tool | What it does |
| Text to your private chat (default) or a group; Markdown, buttons, replies |
— or a rich message (tables, headings, details), or for one member only | |
| A question with answer buttons, then waits for the press or a typed reply |
| Keep waiting for an answer to a message the bot sent |
| One-time upload link: the file is sent when curl finishes |
| A small file passed inline (text or base64) |
| 2–10 photos/videos/documents as one album |
| A map pin or venue |
| A native poll or quiz |
| A live preview of an answer being written (private chat) |
| An interactive HTML widget inside a message (private chat) |
| Change what a widget shows |
| "typing…" before a slow send |
| Change the bot's message text or buttons, e.g. one progress message |
| Delete the bot's message (or yours, in the private chat) |
| Pin or unpin |
| An emoji reaction instead of a reply |
| Copy a message (with its file) into another chat you can access |
| In a personal chat, as you: text, or a file (inline or upload link) |
| Edit a message sent as you |
| Delete a message sent as you |
| Mark a personal chat's latest message read (needs that permission) |
| Your chat, groups, personal chats (with permissions), topics, t.me links |
| Keywords, sender, time, files, topic, or only messages that tag the bot |
| Latest messages in a chat, or the window around one message |
| One message in full, with its reply chain, button presses and reactions |
| Download link for an attachment, and the content when small |
| Read and edit what your assistants keep about each chat (see Memory) |
| Assistant sessions the bot knows of, and whether the relay is up |
| Ask another session something, or hand it a request (needs the relay) |
| Keep waiting for that session's answer |
| Answer a session that asked you |
| Read a call from a chat the bot is not in |
| Answer it, by editing the bot's one message there: text, buttons, media |
| The scene language in brief, and ready scenes to adapt (see Scenes) |
| A message the bot runs by itself: state, screens, rules; or a dry run |
| A scene's state, its creator's note and its latest events |
| Change a scene's state, fire one of its |
| Wait for the next event a scene logs or wakes the assistant with |
| Your saved scenes: every scene created is saved, to reuse or adapt |
| A saved scene's definition, or one of its earlier versions |
| Save a definition under a name, change a saved one (versioned), rename it |
| Delete a saved scene and its earlier versions |
Every send returns a t.me link the assistant can hand you. Buttons are recorded when pressed;
reactions on the bot's messages are recorded too (in groups, that needs the bot to be an admin).
What Telegram added in Bot API 10 is used where it helps:
Rich messages:
send_messageandedit_messagewithformat: "rich"take GitHub-flavoured Markdown with headings, tables, task lists,<details>and formulas, up to 32k characters in one message. Incoming rich messages are read as text.Buttons take a
style(primary, success, danger).For one member only:
only_forshows a group message to a single member (an ephemeral message; the bot must be an admin there). It is not stored.Widgets:
send_widgetsends one self-contained HTML document drawn inside the message. Telegram shows them only in the private chat with the bot for now. A widget's taps reach the bot as queries that must be answered within 15 seconds, so the Worker answers them itself and records each like a button press; the assistant reads them (wait_for_replywithafter_press) and changes what the widget shows withset_widget_state.Polls: quizzes with several right answers, a description, revoting, options added by members, hidden results, a closing time.
Scenes
A scene is a message the bot runs by itself. The assistant describes it once — its state, how the
message looks, and rules for each press, vote, reply or reaction — and goes. From then on the
Worker takes every event, changes the state, redraws the message and answers whoever pressed,
without a session. The assistant is woken only where its own rules call wake().
A scene is yours, not the assistant's: it needs no session and no assistant to run. Any MCP client
can create one (a session id only tells wake() where to go), it keeps running when the assistant
is gone or /disconnected, and you can start a saved one yourself from the bot's menu (below).
On it: a who's-coming list, a checklist, a board for a long task with Pause and Stop, a triage of
findings that wakes the assistant when you press Done, a pinned control panel, tic-tac-toe (with a
bot to play against), Russian checkers, a quiz, mafia with the assistant as host. scene_guide hands
out these as presets to adapt.
{
"title": "Lunch?",
"state": { "yes": {} },
"view": {
"text": "**Coming:** {len(yes)} {join(values(yes))}",
"buttons": [
[
{ "text": "Me", "press": "me" },
{ "text": "Ask Claude", "press": "ask" }
]
]
},
"rules": [
{ "on": "press:me", "do": ["yes[user.id] = user.name"] },
{ "on": "press:ask", "who": "owner", "do": ["wake('ask')"] }
]
}The rules are written in a small language of its own (paths, arithmetic, ?:, a few dozen pure
functions), parsed once when the scene is created and run with a step budget — never eval. Names
and replies from the chat are shown as text, never as markup, and reach the assistant fenced as data.
Who can press what. Anyone in the chat can press a button whose rule says anyone; owner
rules answer only you. Every press gets an answer: the rule's own, or why not ("not now", "only for
@you", "out of date" for an old keyboard or forged button data, "not so fast" past 10 events in 10
seconds per person).
Waking the assistant. A rule with wake() runs only if the wake may happen: it is your press,
or the chat is a group where your assistant answers with «Others too» on; and the limits allow it —
the scene's own wakes an hour (10 by default; change it in the menu: 🎬 Scenes) and the starts every
tag shares. Otherwise the press is refused and nothing changes. When there is simply nobody to wake —
no assistant set up and chosen, and no session behind the scene that anything set up reaches — the
rule runs all the same, its wake() is only logged, and the presser hears that nobody was woken.
Something set up that cannot be reached right now (the relay that carries the scene's session
offline with no routine to start another, settings that no longer read, an owner taken off
ALLOWED_USER_IDS) refuses the press like a limit does ("Nobody can answer right now"), so it can be
tried again. The scene's own limit starts afresh if a scene is finished and created again; the shared
limits do not.
Like a group's sessions of the day, a scene keeps two audiences apart. Your wakes go into the
session that made the scene, where it can take messages, or start a new one. Other members' wakes never go
into that session: the first starts a session of its own for them, and later ones go there where it
can take them (or start another). A session that drives its scene with
update_scene act may wake only itself, and is never taken for you; on a scene that has no
session (one started from the menu, say), any client's act runs its rules without waking anyone. Each wake is a start in the
chat's log (📜 Starts, in a group where your assistant answers).
Cost. A press that changes something is one Worker request; it reads the scene's row and, for
each of its live messages, the stored copy, and writes two rows: the scene and the redrawn message's
record. A press within a second of the last edit writes two more when the held-back edit is made. A
refused press writes nothing, and a press that changes nothing writes nothing (except once a day, to
mark the scene as in use). log() and wake() write one more row each; a scene keeps its latest 200
events. Edits keep to one a second per message. Up to 20 active scenes per person per chat; a scene
nobody used for RETENTION_DAYS ends and is deleted a retention later, and its messages are kept as
long as it is. Scenes end, and their messages lose their buttons, when you lose access to the group
(or let a guest chat go); /disconnect signs assistants out but leaves scenes running — stop them
all with ■ Stop all scenes (in 🎬 Scenes, and under /disconnect's reply). A vote the scene could not take (too fast, a full state) shows as an error in
get_scene, since nobody sees the answer to a vote.
Saved scenes. Every scene an assistant creates is saved in your library, as written, under a name
from its title (counter, кто-идёт, हिंदी-क्विज़, counter-2 when the name is taken; save_as
picks one). A definition already saved is not saved twice, nor is one that differs from a saved one
only in its title or starting state: that is the same scene, started with other values. A later
session lists the library before building a scene and starts one that fits with create_scene
template (with state and title for that run), changes it for good with save_scene and the
version it read — the 20 versions before it are kept — or copies and adapts it under a new name.
🎬 Scenes in the menu. /start → 🎬 Scenes lists your running scenes in every chat, ten a page
(open one to change its wakes an hour or stop it), ■ Stop all scenes (asks first) and 📚 Saved
scenes. Pick a saved scene to read its title, note and what it holds (buttons, links, rules that send
messages, the events that wake the assistant), ▶ start it in your private chat with the bot, or delete
it. ▶ starts the version the card showed, once: if the scene changed meanwhile, or the press is a
second tap, you get the card again. A scene started there is yours and
has no session behind it: everything in it works with no assistant connected, and a wake() starts
your assistant if one is set up, or else wakes nobody and says so. The 20-a-chat limit applies.
Ready-made games. 🎬 Scenes also offers ❌⭕ Tic-tac-toe and ⚪⚫ Checkers, shipped with the bot
(src/scenes/games.ts) in English and Russian and shown even with an empty library. ▶ starts one in
your private chat as yours, like a saved scene, without adding it to your library; a second tap on
the same card starts nothing, even one at the same moment, and neither does a start past 20 running
scenes in the chat (one conditional insert checks both). Tic-tac-toe seats two (or one person on both seats, or you against
🤖, which wins when it can, blocks when it must and otherwise takes the centre or a corner), lights
up whose turn it is, the last move and the winning line, keeps a score and offers a rematch with
sides swapped. Checkers plays Russian draughts on 64 buttons: men step forward and capture both
ways, kings fly, capturing is mandatory, a capture goes on as a chain (the taken pieces stay as ✖
until it ends and cannot be jumped twice; a man crowned mid-chain goes on as a king; a king must land
where it can capture again, when it can), and a side with no move left loses. Draws are by agreement
only. To play with others in a group, ask the assistant: the same games are the tictactoe and
checkers presets.
Up to 100 saved scenes per person. What save_scene made, changed or renamed is kept on purpose; a
new scene makes room only by dropping the auto-saved one unused the longest, and when all 100 were
kept on purpose it runs without being saved. save_scene refuses a new name in a full library.
Saved scenes are not Telegram history: they outlive RETENTION_DAYS and the scenes started from
them, on purpose. They are your own, and go only with delete_saved_scene, or when you are taken off
ALLOWED_USER_IDS. Built-in presets stay as they are.
Scenes were tested against a fake Bot API only. On a live bot, check: the ephemeral reply to a press
(whisper), poll updates reaching the bot, setChatMemberTag (tag, needs the bot to be an admin
with that right), and how fast Telegram lets a busy scene be edited. An existing deployment asks
Telegram for poll updates only once it registers the webhook again: on the next visit to the
Worker's page, or the daily cron.
Memory
Your assistants keep notes about each chat in one Markdown document per chat: me for your private
chat with the bot and things that apply everywhere, and one per group — who is responsible for what,
the project's repository, the tone, and under ## Trust who may ask for what. Every assistant you
connect reads the same memory, so what one learns the others know too. The memory tool works like
Claude's own memory tool (view, create, str_replace, insert, delete), with a chat in place
of a file path.
You see every change: each one arrives silently in your private chat, with what changed, which assistant made it, and an Undo button. Changes in quick succession share one message.
Trust changes only when you ask yourself; assistants are told nothing overrides that.
Menu → Memory lists the chats with memory; read, delete, or erase it all there.
Memory is kept until deleted (not limited to
RETENTION_DAYS). It goes with your access to a group, and when your ID leavesALLOWED_USER_IDS.
Answering from Telegram
Write to the bot or tag it, and your assistant does the work and answers in Telegram. Three can answer, one at a time; choose it in the bot's menu, 🤖 Assistant. Nothing answers until you have chosen one.
Claude: a Claude Code cloud session, run as your routine on your Anthropic account, with the connectors and repositories you give that routine; this bot only starts it. ⚙️ Claude walks you through creating the routine, sends you the prompt to paste into it, and asks for the routine's API trigger id and token.
Codex: the Codex CLI on a machine of yours, signed in to your ChatGPT plan and run by the relay — see Codex on your machine.
OpenAI: sessions on OpenAI's Agents API with your API key, which the Worker runs itself. A chat session answers and hands real work to a task session with a machine of its own; ⚙️ OpenAI sets the models and the webhook that tells you when a session fails.
Keys and tokens go in the private chat, in one message: the bot deletes it, keeps the secret encrypted (with a key derived from the bot token), and starts a test session that answers "ok". No message containing such a key is ever stored, in any chat. Setting one up makes it the one that answers if none does yet (an OpenAI key once its test start went through; Codex when you choose it with its relay online); switching is always yours, in 🤖 Assistant. The others keep their settings, and replies to their sessions' messages still go to them.
What starts a session:
Your private chat with the bot (on once an assistant is set up; 💬 Here turns it off): every message, forwards too — commands aside, and an answer a waiting
ask_userpicks up. Where the session can take messages (Claude's with the relay, below) the day's messages, from 00:00 UTC, go to one session; otherwise each message starts its own. A message right after a start — a forward, then what to do with it — joins that session, which reads the messages around its own.A group, once you turn it on in the group's screen: a mention of the bot, or a reply to a message your assistant sent there. One person per group: whoever turned it on first. If they leave the group, it passes to the next who asks. As in the private chat, the group's tags of the day go to one session, like in the private chat — yours to one, other members' to another, so the session you work in never hears a third party.
Any chat the bot is not in (guest mode): tag the bot there, or reply to its message. Telegram hands the bot that one message and the one it replied to — no history, no members — and lets it post one message per call, which the session then edits: a placeholder at once, the answer when ready. That message can carry inline buttons (link, copy, or recorded presses: up to 200 a call, a press on a replaced keyboard counts for nothing) and become a photo, video, GIF, audio or document by URL — links and media https only, and none of them (nor copy buttons) on a call from someone other than the holder, since a model acting for a third party must not be able to plant a link or make Telegram fetch a URL. That restriction covers buttons, media and scenes only: a Markdown link in the text is not blocked, so the model is told never to put a URL a third party supplied in the text either. Or a scene can run on it (
create_scenewithguest_call, only on the holder's own call and unless the message became media; its link buttons are https only there): presses, toasts, alerts, whispers, screens, wakes — but no post, poll or die, since Telegram lets the bot send nothing else there, and no reply, reaction or vote reaches it. Such a chat is connected like a group: the first call there by someone who may use the bot and has an assistant set up binds the chat to them. From then on their assistant answers there, and other people's calls count only if they turn "Others too" on for that chat (🤖 Assistant → 🕊 Guest chats: others, their hourly limit, the log of starts, disconnect) — under the same rules and limits as in a group. Calls go to that chat's session of the day or start one; a reply to the bot's message there goes to the chat's latest session. Everything else in that chat is a third party's, and what your assistant writes there is seen by everyone in it.Other members of that group too, only if you turn on "Others too" — including messages posted as a channel or as the group, which always count as someone else's. The session helps them with what anyone could do on their own (answers, explanations, web search, talk about the chat). What is yours — connectors, data, memory, other chats, repositories, your account — and running code it uses for them only where your memory for the chat explicitly allows it; it declines the rest and tells you only on signs of abuse. It runs with your connectors, so that is a guard of instructions, not of access. Their starts are limited per chat — 20 an hour by default, 5 to 50 in the group's screen; past that the bot reacts 😴 and tells you quietly, once an hour. A reply of theirs to your assistant's message starts a new session too, told which session wrote it — under the same rules.
Every start goes into the chat's 📜 Starts: who, when, the first words and a link to the session.
Who does the work. Claude's routine runs on Sonnet and does the talking: it answers what it can at
once and hands real work — research, building something, code — to a subagent on Opus, in the
background, so the next message is not kept waiting. An agent sends its result itself and names
itself (agent, next to session); a reply to that message reaches the session marked as that
agent's, and the session passes it on. OpenAI's chat session hands such work to a task session
(start_task); Codex does it itself, on the machine. The prompt — the same core for all three,
with a few lines for each — also tells the assistant to write the way the chat does — its language,
length and tone — rather than as an assistant with a house style.
Tags by another name. If the bot has more usernames than the one BotFather gave it — a
secondary one ending in agent, ai, app or game, which Telegram lets Premium owners assign to
two of their bots, or a collectible one — list them in BOT_USERNAMES (comma-separated), and a tag
by any of them counts.
Never: commands, edits, answers to the bot's own prompts, a reply that a waiting ask_user will
pick up, and — in groups — forwards and messages via inline bots. Each message starts one session at
most, however often Telegram retries it. The bot reacts 👀 when a new session starts (not when a
message goes into one already running); sessions answer by replying to it rather than tagging
anyone. Failures go to your private chat, never to the group. Each start is a session billed by
its provider, and counts toward its limits.
Talking to other sessions
Claude Code cloud sessions cannot be written to from outside: only a full Claude Code sign-in can
put a message into one (OpenAI's sessions take messages from the Worker itself, and Codex's go
through the relay that runs them). A relay can — any always-on Linux machine of yours (an Oracle free
VM will do) signed in to Claude Code. The bot queues messages; the relay asks for them and the
Worker holds the request until one comes, up to 25 s, so a message is on its way within a couple of
seconds — about 3,500 Worker requests a day, a few percent of the free plan. The relay passes each
one on with claude -p --cloud <session>. It needs no open port or domain.
Set it up in the menu: 🤖 Assistant → ⚙️ Claude → 🛰 Relay → 📋 Install command, and run what it sends on the machine:
curl -fsSL https://<your worker>/relay/install.sh | RELAY_TOKEN=relay_… RELAY_AGENT=claude bashA relay serves one assistant, named by RELAY_AGENT (claude or codex, below); the installer
asks for it on the first install rather than assume one, and each screen's command carries its own.
You have one relay: a new install command turns the old one off. It installs curl, jq and Claude
Code if missing and runs the relay as a systemd service. Then sign Claude Code in there once
(claude, then /login) and sudo systemctl restart tg-relay. To update the relay later, run the
same curl … | bash without RELAY_TOKEN and RELAY_AGENT: it keeps the ones it has.
With the relay:
A reply to a session's message goes into that session instead of starting a new one; so do a chat's messages of the day, guest calls among them. Nothing new starts, so the bot puts no 👀 on them.
list_sessionsshows the sessions the bot knows of (started by a tag, wrote through the bot, or were messaged).message_sessionasks one of them something — "how is the migration going?" — or hands it a request, by id or link; the session answers withanswer_session. A session the bot does not know of is reached by its link.A session started by a tag first looks for a session already on the request, and asks it or hands the request over instead of doing the work twice.
Everything passed on arrives marked as data, with who stands behind it by the bot's own records: you, a third party, or unknown (a session the bot did not start). A session started by someone else's tag, or one their replies were passed into, counts as theirs. The receiving session acts for you; for anyone else it gives a short status answer, and more only where the chat's memory Trust allows that person. The label rests on the session id the sender gives: every assistant of yours signs in the same way, so a session talked round can name another's id. It narrows what a message can claim; it is not proof — keep "Others too" where you trust people.
Without a relay, or while it is down, everything works as before: a reply starts a new session that carries on, and the session tools say why another session cannot be reached. If the relay's Claude sign-in expires or it goes quiet, you hear once, and the session that answers instead says so too.
Codex on your machine
A relay can run the Codex CLI, signed in to your ChatGPT plan, as your assistant instead: 🤖
Assistant → ⚙️ Codex → 📋 Install command sends the install command with RELAY_AGENT=codex, which
installs Codex from npm (it needs Node.js) and bubblewrap for the sandbox. Then, once, on that
machine: codex login and sudo systemctl restart tg-relay. With the relay online, choose Codex in
🤖 Assistant.
Codex is not signed in to the bot on that machine. Each job comes with an MCP token of its own,
bound to its session and valid about as long as the run may last (an hour); the relay hands it to
Codex in an environment variable (-c mcp_servers.tg_relay.bearer_token_env_var=TG_MCP_TOKEN),
never on a command line or in the log. Whatever session id a run passes, its calls count as its
own session, so a sandboxed run cannot speak as one of yours. The tokens hang on one sign-in,
Codex runs, listed with the others; removing Codex or losing access revokes it. A Codex session
messaged by a caller that no token binds (a Claude session, say) counts that message as a third
party's.
The relay says what it runs (claude or codex, and codex-sandbox where bubblewrap works) and
is handed only those jobs. A start runs
codex exec --json in the background — three at most at once, one at a time per session — and
tells the bot the thread's id as soon as Codex prints it; messages for that session (replies, the
day's messages, message_session) wait for it and go in with codex exec resume. A start that fails,
or that the relay does not pick up within minutes, is not handed to another provider: you hear why,
once.
Codex runs with your account on that machine, so the screen sets a sandbox policy: Others (the default) sandboxes whatever a third party stands behind — their message, their scene's wake, a session their words went into — All sandboxes everything, None nothing. Without the sandbox Codex has full access, from the working directory you set (your home by default).
A sandboxed run is the whole codex process inside bubblewrap,
in a box of its session's own (~/.tg-relay/sandbox/<session>). It sees, read-only, the system's
programs and libraries (/usr, /bin, /lib*), TLS roots, DNS and hosts files, a two-line
/etc/passwd, and where Node and Codex are installed; and, writable, its own work directory and
Codex home. Your home is an empty tmpfs: no files, SSH keys or the relay's token, and other
processes are hidden (own PID namespace). It keeps the network — Codex needs the model and the bot
— and its environment holds only PATH, HOME, CODEX_HOME, LANG and its MCP token (passed in a
file descriptor, not on bwrap's command line). It does see your Codex login: there is no separate
key, so auth.json is copied into the box for each run (a run can read it) and taken out after; a
login the run refreshed is copied back if it is still the same account. Inside, Codex keeps its own
read-only sandbox as a second layer where the machine allows a sandbox within a sandbox; the relay
checks this when it starts, and where it does not work Codex runs with full access inside the box,
bubblewrap being the boundary (checked with Codex 0.167: the nested sandbox works).
A sandboxed thread lives in its box, apart from yours, and a session stays on the side it started
on: a message that would run on the other side — a third party's reply to your thread, say — starts
a new session that carries on, so their words never go into a thread that runs unsandboxed, and
message_session from such a caller into it is refused. A job keeps the sandbox it was queued with.
The installer checks that bubblewrap works (bwrap --ro-bind / / true). On Ubuntu 24.04 and later
AppArmor may keep it from making a sandbox (kernel.apparmor_restrict_unprivileged_userns=1): the
installer then prints a profile for /usr/bin/bwrap alone and the apparmor_parser command that
loads it. Where bubblewrap does not work, the relay does not say it can sandbox, and sandboxed runs
are refused — you hear why — never run without it. None turns the sandbox off for everyone.
Limits
Cloudflare's limits are per account, shared by every Worker on it. On the free plan:
Resource | Free plan | What this Worker spends |
Worker requests | 100,000 / day | one per Telegram update, one per MCP call |
D1 rows written | 100,000 / day | ~2 per stored message (insert, and the delete at expiry) |
D1 rows read | 5,000,000 / day | a search reads the messages in the window it covers |
D1 storage | 500 MB per database | ~0.5 KB per message |
That is roughly 50,000 stored messages a day across everything on the account. What keeps it low:
Only chats someone connected are written. Messages from other chats are dropped without a write.
messageshas no secondary index (each index entry is one more billed row).OAuth codes, tokens and file links are signed, not stored.
Command answers go back in the webhook response itself, without a separate Bot API call.
A scene writes two rows per press that changes it (the scene and its redrawn message), and nothing for one that does not.
Reads are cheaper but not free: a keyword search scans the stored messages of the chats and time
window it covers (pass since and it starts at that day), so searching a very busy group hundreds
of times a day can reach the read cap. When either D1 cap is hit, D1 refuses all queries until the
next UTC day.
Open mode costs you: with ALLOWED_USER_IDS empty, anyone can add your bot to a busy group and
your account pays for its messages. Every update to a group the bot is in costs a Worker request even
when nothing is stored. Set the allowlist if that matters.
If you outgrow it, the $5 Workers Paid plan includes 10M requests and 50M D1 row writes a month.
Increasing RETENTION_DAYS costs storage, not writes.
Security
Webhook: Telegram's calls are accepted only from its published ranges (
149.154.160.0/20,91.108.4.0/22) and with the secret token registered with the webhook, compared in constant time. The secret is an HMAC of the bot token, not the token itself.Webhook origin: the first public URL the Worker is opened under is where the webhook points, and other hosts (preview URLs, extra routes) cannot move it. To move to a new domain:
bunx wrangler d1 execute telegram-mcp --remote --command "DELETE FROM meta WHERE key IN ('public_origin','webhook_fingerprint')", then open the new URL.One secret: every key (token signing, webhook secret) is derived from
BOT_TOKEN. Revoking the token in BotFather invalidates all sessions and links; the Worker re-registers the webhook on its own (on the next visit to its page, or the daily cron).Login is Telegram Login, checked against the bot token's hash, valid for 10 minutes. OAuth uses PKCE, and codes only go to Claude's and ChatGPT's exact callback URLs or to loopback. Before Telegram's login, a page names the assistant that will get access, and the sign-in can only finish in the browser that saw it, so a link someone else started cannot be accepted by mistake.
Access is checked on every call: your own private chat, groups where you hold a grant and are still a member, and your personal chats while your business connection is on, with only the permissions you gave it in Telegram. Personal messages are keyed by your account, so no query can return them to anyone else. A model cannot post to or read any other chat. It can only edit or delete the bot's own messages, and in a shared group only those sent for the same user.
Refresh tokens rotate: each refresh returns a new one and retires the old. A retired token coming back after its successor was used, or more than 10 minutes later, means someone else holds a copy, and that sign-in's tokens are revoked. An assistant used at least once in 90 days never has to reconnect.
Sign-ins in the bot's menu lists where an assistant is signed in with your account (Claude, ChatGPT, an app on your computer), with when it signed in and was last seen. Signing one out stops its tokens on the next call (tokens issued before this list existed run out within a day instead). Upload and download links it already made keep working until they expire (10 to 15 minutes); signing out everywhere stops those too.
/disconnect(or Sign out everywhere) revokes every token you issued. Your scenes keep running (they need no assistant); ■ Stop all scenes ends them. Removing an ID fromALLOWED_USER_IDScuts access on the next call.What is stored: message text and attachment metadata (Telegram file ids, not the files), for
RETENTION_DAYS. Whoever runs the Worker can read the database. Run your own.
Development
bun installbun testbun run lintbun run devbun test: unit tests plus end-to-end runs of the real Worker against SQLite (behind a D1-shaped adapter) and a fake Bot API. They cover the webhook gate, groups and grants, topics, replies, buttons, file links, OAuth, the allowlist, and concurrent and out-of-order updates.bun run lint: prettier, eslint, tsc (TypeScript 7) and knip. It fixes what it can in place;bun run checkonly reports, and is what CI runs, withbun test, on pushes tomainand on pull requests.bun run devreadsBOT_TOKENfrom.dev.varsor.env. To feed it webhook calls from your machine, also setDEV_SKIP_IP_CHECK=1there (never in production).
wrangler needs Node. On a Bun-only machine, bun add -d node-linux-x64 (or your platform's
package) and put its bin on PATH.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Hosted Telegram MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude Code sessions to Telegram, enabling AI-powered code assistance and file management directly from Telegram chats.88MIT
- FlicenseNot gradedqualityDmaintenanceEnables Claude Code to send messages to and receive instructions from Telegram, with task tracking and persistent storage.-
- FlicenseNot gradedqualityAmaintenanceEnables running Claude Code from Telegram with two-way voice notes, persistent memory across restarts, live tool-call visibility, scheduled reminders, calendar access, and remote permission approvals.-
- AlicenseNot gradedqualityCmaintenanceConnects your own Telegram account or a bot to Claude and other AI assistants so they can read, search, send, and wait for Telegram messages, with everything stored in a local database.MIT