Telegram Mcp Server
Use when calling, operating, or diagnosing the telegram-mcp MCP server (a Telethon/MTProto user-account server, not the Bot API) — making list_chats/get_messages/send_message/wait_for_settled_message calls, an MCP tool call errors or times out, the server appears "sleeping"/unregistered, a Telethon session is invalid or expired, or you need to select or switch between multiple TELEGRAM_SESSION_STRING accounts.
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.
openclaw mcp status telegram-mcp --verbose— static, read-only, opens no connection. Tells you whether the server is registered undermcp.serversinopenclaw.jsonand whether it's enabled.openclaw mcp doctor telegram-mcp --probe --json— actually connects and returns a structuredissueslist. Readissues.
Then match the failure:
| Symptom | Meaning | Action |
|---|---|---|
| Not registered at all | Operator setup gap | Report the exact missing piece + the one-time openclaw mcp add (below). Don't invent a path or silently patch. |
Registered, doctor --probe reports a config issue (bad command, missing cwd, disabled) | Config problem | Report the specific issue text. Don't patch blindly. |
status/doctor are clean but the tool call still errors with an auth failure | Telethon session invalid/expired | Cannot be fixed from here — needs a human-run QR login. See Auth below. |
Registration command (only report it — don't run it for the operator):
openclaw mcp add telegram-mcp --command uv \
--arg --directory --arg <path-to-telegram-mcp> --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_<LABEL> 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: "<that label>"on everylist_chats/get_messages/wait_for_settled_message/send_messagecall this turn. Don't switch labels mid-turn. TELEGRAM_API_ID/TELEGRAM_API_HASHare 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_chatsonce per configured account and report which succeed vs. error — plainlist_chatsonly 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__)
| Tool | Purpose |
|---|---|
list_chats() | List available chats/groups and their IDs (also the simplest connectivity/auth probe) |
get_messages(chat_id, limit) | Read messages from a chat |
send_message(chat_id, text) | Send a message as the account |
wait_for_settled_message(settle_ms=6000, max_wait_ms=50000) | Wait for new messages arriving during the window, with debouncing — does not return pre-existing backlog |
search_messages(...) / search_global(...) | Search message history |
get_chat(chat_id) | Chat info |
get_history(chat_id, ...) | Message history |
Error handling
- On an MCP tool error, retry at most once after a short delay, in the same turn.
- Still failing → run the
status/doctor --probediagnosis above rather than looping or guessing. - Never expose the session string or API keys in any output or log.
Related skills
- Downloads
- 934All time
- Security audit
- Pass
- Last updated
- 4mo ago
- Current version
- v1.0.0
- License
- MIT-0
