Telegram Bot Testing & Verification MCP Server 🤖🧪

A Model Context Protocol (MCP) server that allows AI Coding Agents (such as Antigravity, Claude Desktop, Cursor, and custom agent backends) to autonomously interact with, test, click buttons on, and verify Telegram bots end-to-end.

📖 AI Agents: See the dedicated AI Agent Testing Guide for tool selection workflows, test suites, and best practices.

🌟 Features

• Command & Message Dispatch: Send commands (/start, /help, /settings) and text payloads to any target bot.

• Inline Keyboard Navigation: Click inline callback buttons (CallbackQuery), trigger button menus, and inspect in-place message updates.

• Multi-Step Test Suite Runner (telegram_run_test_suite): Execute full regression test scenarios with assertions and sleep delays in a single tool call.

• Media & File Testing: Send photos, documents, audio, or PDFs to bots, and download returned media to verify generated files.

• Inline Query Mode: Test @bot query inline modes and inspect returned inline articles and preview metadata.

• Python Code Execution Sandbox (telegram_execute_code): Run custom asynchronous Python scripts with direct access to the live TelegramClient and raw MTProto functions.

• Clean State Management: Clear dialog history before/after test runs for idempotent testing.

Related MCP server: telegram-mcp

🚀 Quickstart

1. Clone & Install Dependencies

git clone https://github.com/Fire162/telegram-bot-mcp.git
cd telegram-bot-mcp
pip install -r requirements.txt

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Add your Telegram API credentials from my.telegram.org:

TELEGRAM_API_ID=your_api_id
TELEGRAM_API_HASH=your_api_hash
TELEGRAM_TEST_MODE=false

3. Generate Session (One-Time Login)

Run the interactive login script:

python3 login.py

• Enter your phone number and the verification code sent to your Telegram app.

• The script saves your TELEGRAM_SESSION string automatically into .env.

4. Run the MCP Server

python3 server.py

🔌 Connecting to AI Agents

Antigravity CLI (agy) / Gemini

The repository includes a pre-configured .agents/plugins/telegram-bot/ plugin. Any agy session started in this workspace will automatically discover and load the tools.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "telegram-bot": {
      "command": "python3",
      "args": ["/path/to/telegram-bot-mcp/server.py"],
      "env": {
        "TELEGRAM_API_ID": "your_api_id",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION": "your_session_string",
        "TELEGRAM_TEST_MODE": "false"
      }
    }
  }
}

🛠️ MCP Tools Reference

🧪 Example Test Suite Scenario

[
  {"action": "send", "text": "/start"},
  {"action": "sleep", "seconds": 1.0},
  {"action": "assert_reply", "contains": "Welcome to my bot!"},
  {"action": "click_button", "text": "Settings"},
  {"action": "sleep", "seconds": 0.5},
  {"action": "assert_reply", "contains": "Notification Preferences"}
]

📄 License

MIT License. See LICENSE for details.