# Telegram Bot Testing Mcp

> Write test scenarios for your Telegram bot — Claude runs them like a human QA. MCP server driving the official Telegram Web client in a real browser: structured reads, button presses, files, screenshots, Mini Apps. No MTProto libraries.

- **Type:** MCP server
- **Install:** `agentstack add mcp-0x216-telegram-bot-testing-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [0x216](https://agentstack.voostack.com/s/0x216)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [0x216](https://github.com/0x216)
- **Source:** https://github.com/0x216/telegram-bot-testing-mcp

## Install

```sh
agentstack add mcp-0x216-telegram-bot-testing-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
# 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:

```bash
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):

```bash
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](https://github.com/tdlib/td/issues/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/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: "round_video"` |
| 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 `tg_read_messages`; 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") | ✅ | `forwarded_from: ` |
| 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`, request_contact/location/users buttons | 🔴 | enumerable as text only |
| Keyboard remove / one-time / force_reply | 🟡 | 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_id`s
(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

```bash
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](https://github.com/0x216)
- **Source:** [0x216/telegram-bot-testing-mcp](https://github.com/0x216/telegram-bot-testing-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-0x216-telegram-bot-testing-mcp
- Seller: https://agentstack.voostack.com/s/0x216
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.