Telegram Bot Testing Mcp

telegram-bot-testing-mcp

Write test scenarios for your Telegram bot — Claude runs them like a human QA.

AI agents can already test any website through browser automation. This MCP server gives them the same power over Telegram bots and Mini Apps: it drives the official Telegram Web client (web.telegram.org) in a real browser. Your agent gets exactly the input a real user gets — the same rendered chat, the same keyboards, the same Mini App — so it can verify not just that the bot responds, but that nothing is broken visually: keyboards render in the right shape, edits land, media shows up, the Mini App actually opens.

Instead of clicking through your bot by hand after every deploy, you describe the scenario once and let the agent execute it — sending /commands, pressing the buttons, uploading files, comparing what it sees against what you expected, and attaching screenshots as evidence.

No MTProto libraries, no session-string hacks, no bot token on the user side. Telegram sees a normal, official web client.

Why not telethon / Bot API?

• Bot API shows you the bot's side, not the user's. You can't see how your

keyboard renders, whether the edit landed, or what a real user experiences.

• MTProto userbot libraries (telethon, gramjs, pyrogram) are custom clients:

a different code path from real users, and account-ban-prone.

• This adapter is a real user session in the official client — what your

agent sees is pixel-for-pixel what users see, structurally and visually.

Quickstart

# 1. Install (Python 3.11+; from GitHub until the PyPI release)
uv tool install git+https://github.com/0x216/telegram-bot-testing-mcp
# download the browser (playwright lives inside the tool's env, so go through uvx):
uvx --from git+https://github.com/0x216/telegram-bot-testing-mcp playwright install chromium

# 2. Log in once (opens a browser window — scan the QR with a dedicated account)
telegram-bot-testing-mcp login

# 3. Add to Claude Code
claude mcp add telegram -- telegram-bot-testing-mcp

Then hand your agent a scenario instead of testing by hand:

> Run a regression pass on @my_bot: > 1. /start — the welcome message must show the pricing keyboard, 2 rows of 2. > 2. Press Buy — the bot must edit that message into a payment summary. > 3. Send PROMO2026 — the reply must confirm the discount. > 4. Open the Mini App from the Catalog button and add the first item to cart. > 5. Screenshot every step and flag anything that renders wrong.

The agent executes it step by step with the same input a human tester would have, and reports what passed, what failed, and how it looked.

Tools

| Tool | Purpose | |------|---------| | tg_status | Mode, login state, profile location | | tg_login | One-time interactive login (QR window) | | tg_login_phone / tg_login_code / tg_login_password | Headless login by phone number — the code arrives on the account's other devices | | tg_send_voice | Record & send a real voice message through a fake microphone (WAV input) | | tg_open_chat | Open chat by @username / t.me link | | tg_send_message | Send text or /command; reply_to replies to a specific message | | tg_forward_message | Forward a message via the real forward picker | | tg_send_file | Attach & send photo/document (with caption) | | tg_read_messages | Last N messages as structured JSON (text, buttons grid, media kind, ids) | | tg_wait_for_message | Block until the bot replies — the core test primitive | | tg_click_button | Press an inline button by text or row/col | | tg_click_reply_button | Press a reply-keyboard button | | tg_clear_chat | Wipe history (test isolation) | | tg_screenshot | Screenshot chat / single message / window | | tg_miniapp_open | Open a Mini App from a web-app button | | tg_miniapp_snapshot | List interactive elements inside the Mini App ([ref] role "text") | | tg_miniapp_click / tg_miniapp_type | Interact with Mini App elements by ref | | tg_miniapp_screenshot / tg_miniapp_close | Capture / close the Mini App |

All tools return typed errors with actionable hints (not_logged_in, button_not_found + the buttons that are present, timeout + current chat state, selector_broken when Telegram changes markup).

Configuration

| Env var | Default | Meaning | |---------|---------|---------| | TG_MCP_MODE | prod | prod or test (Telegram test DC, adds ?test=1) | | TG_MCP_HEADED | off | 1 = show the browser window during operations | | TG_MCP_PROFILE_DIR | ~/.telegram-user-mcp/profile- | Browser profile location | | TG_MCP_TIMEOUT_SCALE | 1 | Multiply all network-bound timeouts (e.g. 2 on slow networks / the congested test DC) |

Security

The browser profile directory is your Telegram session — treat it like a password. Use a dedicated test account, not your personal one: any automation that can send messages from your account is worth isolating. The profile stays on your machine; nothing is sent anywhere except to Telegram itself.

Headless servers (CI boxes, VPS)

Everything is headless by default, including login:

telegram-bot-testing-mcp login --phone +42077xxxxxxx
# the confirmation code arrives in the Telegram app on the account's
# other devices (or via SMS) — type it into the terminal prompt

Agents can do the same via tg_login_phone → tg_login_code (→ tg_login_password for 2FA accounts).

Alternatively, log in once on a desktop machine (login opens a QR window) and move the profile — it is just a directory and transfers fine across OSes (verified Windows → Linux):

tar -czf tg-profile.tgz -C ~/.telegram-user-mcp profile-prod
scp tg-profile.tgz server:
ssh server 'mkdir -p ~/.telegram-user-mcp && tar -xzf tg-profile.tgz -C ~/.telegram-user-mcp'

Treat the archive like a password — it contains your session.

Testing against the Telegram test DC

Telegram runs a separate test environment, and TG_MCP_MODE=test targets it. Reality check as of 2026:

1. Auto-created test accounts are disabled. The documented 99966XYYYY

numbers with deterministic codes no longer work (tdlib/td#3370 — "Test accounts are disabled currently"). Don't believe older tutorials.

1. Register with a real phone number via the official iOS app: tap the

Settings icon 10 times → Accounts → Login to another account → Test.

1. Log the adapter in: TG_MCP_MODE=test telegram-bot-testing-mcp login —

scan the QR with the test-mode iOS app.

1. Create your bot inside the test DC: message @BotFather *from the test

account* — it's a separate BotFather with separate tokens.

1. Point your bot's code at the test Bot API route:

https://api.telegram.org/bot/test/METHOD (the bot is a token, not a phone number — one test account can create the bot and act as the user).

For most workflows the default prod mode with a dedicated account is simpler.

Coverage map

The single source of truth for what this adapter can and cannot test. Statuses are earned, not promised:

• ✅ implemented and verified by a live e2e run against real Telegram
• 🟡 implemented, no dedicated e2e yet (should work; treat with care)
• 🔴 not implemented (PRs / issues welcome; priorities below)
• ⚪ impossible in the official Telegram Web client itself — a human

web user can't do it either, so a web-based tester can't and shouldn't

Reading what the bot sends

| Component | Status | Notes | |---|---|---| | Text, emoji, line breaks | ✅ | emoji restored from `, preserved | | Formatting entities (bold/links/code/spoilers) | 🟡 | extracted as plain text; markup structure not exposed | | Photo | ✅ | media: "photo" | | Video | 🟡 | media: "video" | | GIF / animation | ✅ | detected as video | | Video note (round) | 🟡 | media: "roundvideo" | | Voice | ✅ | media: "voice" | | Audio file | 🟡 | media: "audio" | | Document | 🟡 | media: "document" (sending verified, receiving not) | | Sticker (static/animated/video) | 🟡 | media: "sticker" | | Album / media group | 🟡 | read as one message; items not split out | | Message edit by bot | ✅ | verified via re-read after callback | | Message deletion by bot | 🟡 | disappears from tgreadmessages; no explicit event | | Location | ✅ | media: "location" | | Venue | ✅ | media: "venue", title/address in text | | Live location | 🟡 | detected as location; live updates not tracked | | Contact | ✅ | media: "contact", name/number in text | | Poll / quiz | ✅ | poll: {question, options}; vote counts not yet | | Dice / darts / slots | ⚪ | the web client renders them as plain animated stickers — indistinguishable | | Invoice (payments) | 🔴 | Pay button is enumerable; checkout flow unsupported | | Forward header ("Forwarded from") | ✅ | forwardedfrom: | | Reply-to attribution | ✅ | reply_to: {title, quote} | | Sender attribution | 🟡 | sender field; only rendered in group-like contexts (untested) | | Reactions set by the bot | 🔴 | | | Link preview / web page card | 🔴 | text extracted, preview card not flagged | | Service messages | ✅ | flagged service: true` |

Buttons & keyboards

| Component | Status | Notes | |---|---|---| | Inline callback buttons (grid, click, edit-after-callback) | ✅ | | | Reply keyboard (show, click, toggle) | ✅ | | | web_app buttons → Mini App | ✅ | see Mini Apps below | | URL buttons | 🟡 | enumerated with text; clicking (opens a new tab) undefined | | login_url, switch_inline_query, requestcontact/location/users buttons | 🔴 | enumerable as text only | | Keyboard remove / one-time / forcereply | 🟡 | not explicitly tracked | | Bot commands menu (/) and menu button | 🔴 | |

Acting as the user

| Action | Status | Notes | |---|---|---| | Send text / commands / emoji | ✅ | delivery-verified (not just typed) | | Send photo / document (+caption) | ✅ | kind: auto\|photo\|document | | Record & send voice | ✅ | fake microphone fed from WAV | | Press START on a new bot | ✅ | automatic | | Clear chat history (test isolation) | ✅ | | | Screenshots (chat / message / window) | ✅ | | | Send video note (webcam round) | 🔴 | possible via fake video device; not implemented | | Send sticker / GIF (pickers) | 🔴 | | | Create a poll | 🔴 | web client supports it; not implemented | | Forward a message | ✅ | tg_forward_message via the real picker; bot-side receipt verified | | Reply to a specific message | ✅ | tg_send_message(reply_to=...); bot-side receipt verified | | Edit / delete own message | 🔴 | | | Set a reaction | 🔴 | | | Inline mode (@bot query + result picker) | 🔴 | biggest gap for inline bots | | /start deep link with payload (?start=...) | 🔴 | | | Block / restart bot, profile actions | 🔴 | | | Send location / live location | ⚪ | the official web client cannot | | Calls, secret chats | ⚪ | not available on web / not applicable to bots | | Stories | ⚪ | bots don't interact with stories |

Sessions & flows

| Flow | Status | Notes | |---|---|---| | QR login (desktop window) | ✅ | manual scan once | | Headless phone login (terminal / MCP tools) | ✅ | autonomous e2e: second session reads the code | | 2FA password step | 🟡 | implemented; test account has no 2FA to verify against | | Profile transfer to servers | ✅ | verified Windows → Linux | | Mini App: open / snapshot / click / type / read state / screenshot / close | ✅ | | | Mini App main button / back button | 🟡 | selectors present, no e2e | | Payment checkout (test provider) | 🔴 | feasible on the test DC | | Groups / channels / topics | 🔴 | designed for 1:1 bot chats so far |

Roadmap order for the 🔴s: (1) inline mode; (2) payment checkout on the test DC; (3) sticker/GIF pickers; (4) groups/channels.

Note on message ids: they are the web client's DOM ids. All adapter tools speak them consistently, but they can diverge from Bot API message_ids (observed after a history clear) — never compare the two directly.

Limitations

• One server instance per profile (Chromium locks the profile directory).
• Telegram Web markup changes can break selectors — they live in one file

(selectors.py), and every breakage surfaces as a typed selector_broken error. PRs welcome.

Development

uv venv && uv pip install -e ".[dev]" && playwright install chromium
python -m pytest             # unit tests (offline, fixture DOM)
python e2e/fixture_bot.py    # BOT_TOKEN=... — the e2e fixture bot
python e2e/run_scenarios.py  # BOT=@your_fixture_bot — full scenario run

MIT license.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0x216
• Source: 0x216/telegram-bot-testing-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.