Telegram Mcp Server

Operating the telegram-mcp Server

Overview

telegram-mcp is an MCP server (backed by Telethon/MTProto) that exposes a real Telegram user account as stateless tools — not a bot, no bot token, no Bot API. This skill covers one thing: how to make a successful call to that server and know it worked — lifecycle, diagnostics, auth, multi-account. It has no opinion on monitoring flows or reply voice.

OpenClaw owns the server's stdio child process like any mcp.servers entry: it launches lazily on the first tool call and reaps it after mcp.sessionIdleTtlMs idle (default 10 min). "Sleeping" is normal — the next call respawns it transparently. Never run uv run main.py &, pkill, or any manual process command against it — that fights OpenClaw's supervision and can leave a second conflicting Telethon session logged in under the same account.

Making a call (do this first)

Just call it. Call mcp__telegram-mcp__list_chats. If the server was idle, the first call may take a moment to respawn — that's expected, don't retry-loop on it. Once it succeeds, proceed with whatever you were doing; don't re-run diagnostics mid-turn after a success.

When a call errors — diagnose, don't guess

Run these in order (via your exec tool). Read structured output, not free text.

1. openclaw mcp status telegram-mcp --verbose — static, read-only, opens no connection. Tells you whether the server is registered under mcp.servers in openclaw.json and whether it's enabled.
2. openclaw mcp doctor telegram-mcp --probe --json — actually connects and returns a structured issues list. Read issues.

Then match the failure:

Registration command (only report it — don't run it for the operator):

openclaw mcp add telegram-mcp --command uv \
  --arg --directory --arg  --arg run --arg main.py

plus the required env: TELEGRAM_API_ID, TELEGRAM_API_HASH, and a session string (see Auth). Don't invent a path you don't actually know.

Auth failure (the one thing you can't fix)

A Telethon session string that is invalid or expired won't show up in doctor's static checks — doctor doesn't understand Telegram app-level auth, so it only surfaces as an error from the real tool call. Generating a new session string requires an interactive QR login in a real, human-attended terminal:

uv run session_string_generator.py --qr

This cannot be scripted, piped, or run through a non-TTY automation shell. Tell the user precisely that; do not attempt to run the generator or edit the session string yourself, and never expose a session string or API key in output.

Multi-account

The server never picks or remembers an "active" account — it just accepts an optional account param on every tool call once more than one TELEGRAM_SESSION_STRING_ is configured in its env. Tracking "active" is a caller/plugin concern, not the server's.

• If your instruction context names an active account label, pass account: "" on every list_chats/get_messages/wait_for_settled_message/send_message call this turn. Don't switch labels mid-turn.
• TELEGRAM_API_ID/TELEGRAM_API_HASH are shared across all accounts (one app registration can log in as many accounts). Only the session string varies per label.
• To test one account's auth specifically, call list_chats once per configured account and report which succeed vs. error — plain list_chats only tests whichever account you happened to pass.
• Adding a brand-new account still requires the human-run QR login above — you cannot generate a session string yourself, for a first account or an additional one.

Tool reference (prefix: mcp__telegram-mcp__)

Error handling

1. On an MCP tool error, retry at most once after a short delay, in the same turn.
2. Still failing → run the status / doctor --probe diagnosis above rather than looping or guessing.
3. Never expose the session string or API keys in any output or log.