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.

Related MCP server: QA Agent Pro

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

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

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.

2. Register with a real phone number via the official iOS app: tap the Settings icon 10 times → Accounts → Login to another account → Test.

3. Log the adapter in: TG_MCP_MODE=test telegram-bot-testing-mcp login — scan the QR with the test-mode iOS app.

4. Create your bot inside the test DC: message @BotFather from the test account — it's a separate BotFather with separate tokens.

5. Point your bot's code at the test Bot API route: https://api.telegram.org/bot<token>/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

Buttons & keyboards

Acting as the user

Sessions & flows

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.