The MCP server

tg mcp hands a profile to an agent over MCP, on stdin and stdout, with no network port. The server comes with tg; there is nothing else to install.

When you need it. In Claude Code, Codex and other agents with a terminal, tg itself is enough — it costs the same tokens and can do the same things. MCP is for clients without a terminal, such as Claude Desktop or Cursor's chat, and for anyone who wants the client to ask before each send. ChatGPT or Claude in the browser need more than this — see remote.md.

This server is copied from max-cli's (max mcp) and behaves the same way.

ConnectingCopy Anchor Link

Log in in a terminal first, as usual (tg session start). The server never logs in.

Claude Code:

claude mcp add tg -- tg mcp

With a profile — it goes first, as in any command:

claude mcp add tg-work -- tg work mcp

Claude Desktop, Cursor and others: tg prints the entry for their settings file:

tg mcp config
tg work mcp config --confirm-send     # the entry with a form before every change

--confirm-send, --allow-dangerous and --yes go into the entry as given (below).

{
  "mcpServers": {
    "tg": {
      "type": "stdio",
      "command": "/usr/bin/node",
      "args": ["/usr/lib/node_modules/@leemour/tg-cli/dist/bin/tg.js", "mcp"],
      "env": { "XDG_RUNTIME_DIR": "/run/user/1000" }
    }
  }
}

Paste the entry under mcpServers in the client's settings file: for Claude Desktop that is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows; for Cursor, ~/.cursor/mcp.json. The command writes nothing itself.

The paths are full because a client started from the desktop does not see the terminal's PATH, and on Windows tg is a tg.cmd file that a client without a shell cannot start. The entry copies TG_CONFIG_DIR, TG_STATE_DIR, TG_CACHE_DIR, MESSAGING_STORE and XDG_RUNTIME_DIR when they are set; never TG_API_ID, TG_API_HASH or the session.

If Node came from nvm, fnm or Volta, its path belongs to one Node version — run tg mcp config again after changing it. From npx the command refuses: npx's cache is cleared, and the path would stop existing.

⚠ TG_CONFIG_DIR, TG_STATE_DIR and TG_CACHE_DIR change where the login is looked for. If they are set in the terminal and not for the MCP client, or the other way round, the server answers "no session" although tg works in the terminal. Set them the same in both, or in neither.

⚠ On Linux the app credentials are in the keyring, which is reached through XDG_RUNTIME_DIR. A client that starts servers with a trimmed environment leaves it out, and every tool then answers that the keyring is probably out of reach. The entry from tg mcp config includes it.

What an agent may doCopy Anchor Link

The profile's permissions decide which tools an agent is offered, by the same levels as the commands (configuration.md):

With the default settings an agent can send, edit, react, forward, pin, vote and mark a chat read, with no flag and no question. Only tg_messages_delete is at ask: you see a form before each deletion. An agent never deletes for everyone and never ends your other sessions, whatever the level.

To keep an agent read-only, give it a profile of its own — tg agent session start logs it in, as another device of the same account — and set each resource there:

for key in messages reactions polls topics chats contacts account; do
  tg agent config set permissions.$key readonly
done
claude mcp add tg -- tg agent mcp

readOnly: true in that profile does the same, as an older setting. To have the agent ask before each send, set messages.send to ask:

tg agent config set permissions.messages.send ask

The levels bind you too: in that profile your own tg agent messages send asks as well. Two flags skip the form for the levels at ask:

• tg mcp --allow-dangerous — no form before a deletion;
• tg mcp --yes — no form before any other change.

A send, an edit or a forward over MCP goes through the same checks as its command: the profile's permissions, the list of allowed recipients, the hourly limit, and the journal of sends (tg sends list). On top of that every writing tool is marked as dangerous: VS Code and Cursor ask before every call, and Claude Code, by its documentation, shows an approval dialog even where everything else is allowed in advance.

Marking a chat read is chats.mark-read: the other side sees that you read it. Set it to readonly when an agent reads on your behalf and should not give that away. tg_chats_mark_read never counts toward the hourly limit.

Deleting is messages.delete. tg_messages_delete removes up to 10 messages from your view only; deleting for everyone is left to the command, typed by you. In a supergroup or a channel Telegram has no "for me only", so there the tool is refused.

--allow-send, --allow-mark-read and --allow-delete decide nothing: they are accepted with a warning so an agent set up with them still starts. Remove them from the client's settings.

A confirmation form from the server itselfCopy Anchor Link

claude mcp add tg -- tg mcp --confirm-send

The server shows a form before a change whose level is ask, and with --confirm-send before every change, whatever its level. A send's form shows which chat — the title and id the agent's name resolved to — and the whole text. The change goes only after Accept; the form has no fields, only the one button. The client's own window shows the arguments as the model wrote them (chat: "Anna"); the form shows what you are actually agreeing to ("Anna Petrova (123456)").

• Decline, or closing the form: nothing is changed, and the agent gets confirmation_required and must not try again.
• A client that cannot show forms gets an error — nothing is changed. Claude Code shows forms.
• The yes is bound to what the form showed: if the agent changes the chat, the text or the tool after confirming, nothing is changed.
• A yes works once, for 5 minutes. Replaying the same answer changes nothing.

ToolsCopy Anchor Link

Answers are what the command prints with --json: a list is { items, page, limit, hasMore }, a chat's messages { items, limit, hasMore }, ids are strings. An error is { error: { code, message, … } } with the CLI's codes; an ambiguous chat name answers with the candidates.

Every read is saved to the local store, as a command's is, and each call can be kept as a run (tg runs list), named mcp chats list and so on.

Prompts, and chats by @Copy Anchor Link

The server offers four ready prompts — in Claude Code they are / commands:

reply and review send through tg_messages_send, so where messages.send is readonly the agent only shows the drafts.

Chats are resources tg://chat/<id> — in Claude Code you can mention them with @. A resource is the chat and its recent messages. The list comes from the local store and never connects to Telegram; until something was read, it is empty. Only reading one chat connects.

How it holds the connectionCopy Anchor Link

The first call connects to Telegram, and the next ones reuse the connection. It closes after 2 minutes without a call, and in any case 5 minutes after it opened, so a long agent session never reads a stale snapshot. The next call connects again. Calls run one at a time, even when the client sends them together.

The server exits as soon as the client closes stdin, and closes its connection to Telegram.