🤖 Telegram MCP

Autonomous Bot Testing, Automation & MTProto Control for AI Coding Agents

Model Context Protocol (MCP) server for testing, automating, and interacting with Telegram bots via native MTProto.
Includes 62 tools for button clicks, messages, media verification, polls, Telegram Mini App launch URLs, and custom MTProto scripts.

Warning

Disclaimer: This project is an independent open-source tool and is not affiliated with, authorized, maintained, sponsored, or endorsed by Telegram FZ-LLC, Telegram Messenger Inc., or any of their affiliates. "Telegram" is a registered trademark of its respective owners.

Tip

Environment Recommendation: We strongly recommend using the Test Server (TELEGRAM_TEST_MODE=true) for active bot development and automated verification. It carries zero risk to your main personal Telegram account. Make sure your target bot and user account are on the same environment (Test Bot ↔ Test Account, or Prod Bot ↔ Prod Account).

📑 Table of Contents

🌟 Features
🏗️ System Architecture
⚡ Companion Terminal CLI (tg-cli)
🚀 Setup & Installation
- Option A: 🤖 Automated Setup via AI Agent
- Option B: 🛠️ Manual Setup
🔌 Connecting to AI Agents
🛠️ MCP Tools Matrix (62 Tools)
🧪 Example Multi-Step Test Scenario
🛡️ Security & Session Protection
🔬 Running Unit Tests
📄 License

🌟 Features

💬 Autonomous Bot Interaction: Send commands (/start, /help), dispatch formatted Markdown/HTML messages, quote text, and await bot replies.
🎛️ Keyboards & Telegram Mini Apps: Click inline keyboard buttons (CallbackQuery), click bottom reply buttons (ReplyKeyboardMarkup), and extract authenticated Web App launch URLs (messages.RequestWebViewRequest) for Playwright/browser testing.
🖼️ Rich Media & File Verification: Upload documents, photos, audio, or circular voice notes, and download bot-generated media for visual and payload verification.
🗳️ Native Polls & Quizzes: Dispatch single/multi-choice polls and programmatically vote or retract votes.
👥 Chat Moderation & Admin Event Log: Inspect administrative audit logs (bans, kicks, permissions, title changes, deletions), create disposable test supergroups, and manage invite links.
⚡ Arbitrary MTProto Execution Sandbox (telegram_execute_code): Direct access to the live Telethon.TelegramClient instance, raw TL functions, types, and event streams.
🛡️ Dual-Mode Session Auth & Mismatch Shield: Connect using either interactive StringSession or existing SQLite .session file paths, protected by an automatic DC environment mismatch shield.

🏗️ System Architecture

flowchart TD
    subgraph Agents ["AI Coding Agents & IDEs"]
        AgentA["Antigravity CLI (`agy`)"]
        AgentB["Claude Desktop"]
        AgentC["Cursor / Windsurf"]
        AgentD["Cline / Roo Code"]
    end

    subgraph MCP ["MCP Server Layer (server.py)"]
        MCPEngine["MCP Protocol Engine (JSON-RPC over stdio)"]
        Tools["62 Registered MCP Tools"]
    end

    subgraph Service ["telegram-mcp Service Core (telegram_service.py)"]
        Lock["Process Lock (/tmp/telegram-mcp.lock)"]
        Shield["Environment Mismatch Shield"]
        Auth["Session Manager (SQLite .session / StringSession)"]
        Client["Telethon MTProto Engine"]
    end

    subgraph Telegram ["Telegram MTProto Network"]
        TestCluster["Test Server Cluster (DC 2 Sandbox)"]
        ProdCluster["Production Server Cluster (Live Network)"]
    end

    Agents -->|MCP Protocol / stdio| MCPEngine
    MCPEngine --> Tools
    Tools --> Lock
    Lock --> Shield
    Shield --> Auth
    Auth --> Client
    Client -->|TELEGRAM_TEST_MODE=true| TestCluster
    Client -->|TELEGRAM_TEST_MODE=false| ProdCluster

⚡ Companion Terminal CLI (`tg-cli`)

Looking for a human-friendly command-line interface to test bots, inspect chat history, and switch sessions directly from your terminal?

Check out telegram-mcp-cli:

# Install the companion CLI
pip install git+https://github.com/Telegram-mcp/telegram-mcp-cli.git

# Point directly to any existing Telethon .session file
tg-cli auth /path/to/my_account.session

# Inspect connection & environment alignment
tg-cli status

# Send commands and inspect responses
tg-cli command @BotFather /start

🚀 Setup & Installation

Option A: 🤖 Automated Setup via AI Agent (Recommended)

Paste this prompt directly into your AI assistant (Antigravity CLI, Cursor, Claude Code, Cline, Roo Code, or Windsurf):

Tip

Copy-Paste Prompt for your AI Assistant:

Set up the Telegram MCP server for me:
1. Clone & Navigate: Check if the repository is already present; if not, clone it and enter the directory:
   git clone https://github.com/Telegram-mcp/telegram-mcp.git
   cd telegram-mcp
2. Dependencies: Ensure Python 3.10+ is available and install dependencies:
   pip install -r requirements.txt
3. Configuration: Copy `.env.example` to `.env`. Prompt me for my Telegram `TELEGRAM_API_ID` and `TELEGRAM_API_HASH` (from https://my.telegram.org), and ask whether I prefer Test Server (`TELEGRAM_TEST_MODE=true`, recommended) or Production (`false`).
4. Telegram Login: Run `python3 login.py` interactively so I can authenticate, or let me specify an existing `TELEGRAM_SESSION_PATH`.
5. MCP Registration: Register this MCP server in my AI client configuration:
   - Command: `python3`
   - Args: `["<absolute-path-to-telegram-mcp>/server.py"]`
6. Verification: Call `telegram_status` to verify that the connection is healthy and all 62 tools are loaded.

Option B: 🛠️ Manual Setup

1. Clone & Install Dependencies

git clone https://github.com/Telegram-mcp/telegram-mcp.git
cd telegram-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=true

3. Configure Telegram Session

Choose either authentication method:

Method 1 (Interactive Phone/QR Login):
```
python3 login.py
```
Generates and saves your TELEGRAM_SESSION string into .env.
Method 2 (Direct .session SQLite File): If you already have an existing Telethon .session file:
```
TELEGRAM_SESSION_PATH=/absolute/path/to/your.session
```
(The server will automatically load and authorize directly from your file without running login.py).

4. Run the MCP Server

python3 server.py

🔌 Connecting to AI Agents

Antigravity CLI (`agy`)

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

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor / Cline / Roo Code / Windsurf

Add to your .cursor/mcp.json or Cline/Roo MCP settings:

{
  "mcpServers": {
    "telegram-bot": {
      "command": "python3",
      "args": ["/path/to/telegram-mcp/server.py"]
    }
  }
}

🛠️ MCP Tools Matrix (62 Tools)

💬 Messaging, Commands & Replies

Tool Name	Parameters	Description
`telegram_send_command`	`bot_username`, `command`, `wait_response?`, `timeout_seconds?`	Sends `/start`, `/help`, etc. and receives bot reply with button metadata.
`telegram_send_message`	`bot_username`, `text`, `reply_to_msg_id?`, `parse_mode?`	Sends formatted text queries or messages (Markdown/HTML).
`telegram_edit_message`	`bot_username`, `message_id`, `new_text`, `parse_mode?`	Edits previously sent messages.
`telegram_delete_messages`	`bot_username`, `message_ids`, `revoke?`	Deletes messages by ID.
`telegram_forward_messages`	`to_chat`, `from_chat`, `message_ids`	Forwards messages between chats.
`telegram_send_reaction`	`bot_username`, `message_id`, `reaction`	Sends emoji reactions (👍, 🔥, ❤️, etc.).
`telegram_click_reply_button`	`bot_username`, `button_text?`, `button_index?`	Clicks buttons in persistent bottom reply keyboards.
`telegram_send_and_verify`	`bot_username`, `input_text`, `expected_contains`	Single-step assertion check for automated tests.
`telegram_run_test_suite`	`bot_username`, `steps`	Runs multi-step test workflows with assertions and delays.

🎛️ Interactive Buttons, Mini Apps & Waiting

Tool Name	Parameters	Description
`telegram_click_inline_button`	`bot_username`, `message_id?`, `button_text?`, `button_index?`	Triggers inline keyboard callback queries.
`telegram_inline_query`	`bot_username`, `query`	Tests `@bot query` inline modes and inspects results.
`telegram_get_web_app_url`	`bot_username`, `message_id?`, `button_text?`, `button_index?`	Extracts authenticated Web App launch URLs from Telegram Mini App buttons.
`telegram_wait_for`	`bot_username`, `text_contains?`, `after_message_id?`, `wait_for_edit?`	Explicitly waits for incoming bot replies or message edits.
`telegram_send_chat_action`	`bot_username`, `action?`	Broadcasts chat presence indicators (`typing`, `upload_photo`, etc.).

🖼️ Media, Photos, Audio & Location

Tool Name	Parameters	Description
`telegram_send_file`	`bot_username`, `file_path`, `caption?`, `voice_note?`	Sends photos, documents, audio, or circular voice notes.
`telegram_send_album`	`bot_username`, `file_paths`, `caption?`	Sends multiple media files grouped as an album.
`telegram_download_media`	`bot_username`, `message_id`, `output_dir?`	Downloads media attachments from bot messages.
`telegram_download_profile_photo`	`bot_username`, `output_dir?`	Downloads avatars/profile photos of users, bots, or groups.
`telegram_search_media`	`bot_username`, `media_type?`, `query?`, `limit?`	Searches chat history filtered by specific media types.
`telegram_send_location`	`bot_username`, `latitude`, `longitude`, `title?`, `address?`	Sends geographic coordinates or named venues.

🗳️ Polls & Quizzes

Tool Name	Parameters	Description
`telegram_send_poll`	`bot_username`, `question`, `options`, `is_quiz?`, `correct_option_id?`	Creates native polls or quiz questions.
`telegram_vote_poll`	`bot_username`, `message_id`, `option_index`	Votes on a poll or quiz option.
`telegram_retract_vote`	`bot_username`, `message_id`	Retracts a previously cast vote.

👥 Chat Management, Moderation & Admin Logs

Tool Name	Parameters	Description
`telegram_get_admin_log`	`chat_identifier`, `limit?`, `query?`, `ban?`, `kick?`, `edit?`, `delete?`	Inspects administrative audit logs of supergroups/channels.
`telegram_edit_chat_info`	`chat_identifier`, `title?`, `about?`	Programmatically updates chat title or description text.
`telegram_create_chat`	`title`, `about?`, `megagroup?`, `for_forum?`	Creates disposable test supergroups, channels, or forum supergroups.
`telegram_delete_chat`	`chat_identifier`	Permanently deletes a channel or supergroup.
`telegram_create_invite_link`	`chat_identifier`, `title?`, `expire_in_seconds?`, `usage_limit?`	Generates customizable chat invite links.
`telegram_join_chat`	`chat_identifier`	Joins public channels or private chats via invite links.
`telegram_leave_chat`	`chat_identifier`	Leaves a channel or group.
`telegram_get_chat_members`	`bot_username`, `limit?`	Lists group participants with IDs, roles, and bot flags.
`telegram_get_participant_permissions`	`chat_identifier`, `user_identifier`	Inspects admin rights and restriction rules of a chat member.
`telegram_block_peer`	`peer_identifier`	Blocks a user or bot.
`telegram_unblock_peer`	`peer_identifier`	Unblocks a previously blocked peer.
`telegram_get_blocked_peers`	`limit?`	Retrieves list of all currently blocked peers.

📁 Organization, Dialogs & History

Tool Name	Parameters	Description
`telegram_list_dialogs`	`limit?`	Lists recent chats, groups, bots, and channels with unread counts.
`telegram_get_chat_history`	`bot_username`, `limit?`	Retrieves conversation history with full message structure.
`telegram_get_message_context`	`bot_username`, `message_id`, `limit_before?`, `limit_after?`	Fetches surrounding conversation context around a message.
`telegram_search_messages`	`bot_username`, `query`, `limit?`	Searches message history by keyword.
`telegram_export_chat`	`bot_username`, `limit?`, `format?`	Exports conversation history as clean Markdown or JSON for AI processing.
`telegram_clear_chat`	`bot_username`	Clears dialog history for clean test states.
`telegram_mark_chat_read`	`bot_username`, `max_id?`	Marks messages in a chat as read.
`telegram_pin_message`	`bot_username`, `message_id`, `notify?`	Pins messages in bot or group chats.
`telegram_unpin_message`	`bot_username`, `message_id?`	Unpins messages in a chat.
`telegram_get_pinned_messages`	`bot_username`, `limit?`	Retrieves pinned messages from any chat.
`telegram_save_draft`	`bot_username`, `text`, `reply_to_msg_id?`	Saves an uncommitted draft into the chat input field.
`telegram_schedule_message`	`bot_username`, `text`, `schedule_in_seconds?`	Schedules future automated delivery of a message.
`telegram_get_scheduled_messages`	`bot_username`	Retrieves queued scheduled messages.
`telegram_delete_scheduled_messages`	`bot_username`, `message_ids`	Cancels scheduled messages.
`telegram_mute_chat`	`bot_username`, `duration_seconds?`	Mutes chat notifications.
`telegram_unmute_chat`	`bot_username`	Unmutes notifications.
`telegram_get_dialog_filters`	None	Retrieves configured Telegram chat folders/filters.
`telegram_create_dialog_filter`	`title`, `emoticon?`, `filter_id?`, `bots?`, `groups?`	Creates a new Telegram chat folder/filter.
`telegram_delete_dialog_filter`	`filter_id`	Deletes a Telegram chat folder/filter by ID.
`telegram_send_saved_message`	`text?`, `file_path?`	Writes directly to Telegram 'Saved Messages' cloud chat.
`telegram_get_saved_messages`	`limit?`	Reads notes and artifacts from Telegram 'Saved Messages'.
`telegram_get_contacts`	`query?`, `limit?`	Retrieves saved contacts with privacy-masked phone numbers.

⚡ MTProto Sandbox & Diagnostics

Tool Name	Parameters	Description
`telegram_status`	None	Diagnostics for connection health, session mode, environment match, and user profile.
`telegram_execute_code`	`code`, `timeout_seconds?`	Executes arbitrary Python code with direct access to `client`, `functions`, and `types`.
`telegram_get_bot_info`	`bot_username`	Retrieves registered commands, description, and about text.
`telegram_get_user_profile`	`user_identifier`	Inspects full user/bot profile metadata, Premium badge, and verification status.
`telegram_resolve_peer`	`peer`	Resolves username, phone, or ID into detailed entity metadata.

🧪 Example Multi-Step Test Scenario

Using telegram_run_test_suite, an AI agent can execute an entire regression scenario in a single tool call:

[
  {"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"}
]

🛡️ Security & Session Protection

Exclusive Process Lock (/tmp/telegram-mcp.lock): Telegram permanently revokes session keys on duplicate connections (AuthKeyDuplicatedError). The server uses an OS-level flock to ensure no two processes run concurrently.
Environment Mismatch Shield: Automatically inspects the Data Center IP of the session. If TELEGRAM_TEST_MODE does not match the session cluster (Test vs. Production), the server halts with a clear error before Telegram rejects the key.
Phone Privacy: User phone numbers are masked (+16 ***** 4502) in all status outputs and logs.

🔬 Running Unit Tests

Run the test suite with pytest:

pip install -r requirements-dev.txt
python3 -m pytest tests -v

📄 License

This project is open source under the MIT License.

Name		Name	Last commit message	Last commit date
.agents/plugins/telegram-bot		.agents/plugins/telegram-bot
.github		.github
assets		assets
docs		docs
tests		tests
.env.example		.env.example
.gitignore		.gitignore
AGENT.md		AGENT.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
login.py		login.py
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
server.py		server.py
telegram_service.py		telegram_service.py

Navigation Menu

Repository navigation

About

Repository files navigation

🤖 Telegram MCP

Autonomous Bot Testing, Automation & MTProto Control for AI Coding Agents

📑 Table of Contents

🌟 Features

🏗️ System Architecture

⚡ Companion Terminal CLI (`tg-cli`)

🚀 Setup & Installation

Option A: 🤖 Automated Setup via AI Agent (Recommended)

Option B: 🛠️ Manual Setup

1. Clone & Install Dependencies

2. Configure Environment

3. Configure Telegram Session

4. Run the MCP Server

🔌 Connecting to AI Agents

Antigravity CLI (`agy`)

Claude Desktop

Cursor / Cline / Roo Code / Windsurf

🛠️ MCP Tools Matrix (62 Tools)

🧪 Example Multi-Step Test Scenario

🛡️ Security & Session Protection

🔬 Running Unit Tests

📄 License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🤖 Telegram MCP

Autonomous Bot Testing, Automation & MTProto Control for AI Coding Agents

📑 Table of Contents

🌟 Features

🏗️ System Architecture

⚡ Companion Terminal CLI (tg-cli)

🚀 Setup & Installation

Option A: 🤖 Automated Setup via AI Agent (Recommended)

Option B: 🛠️ Manual Setup

1. Clone & Install Dependencies

2. Configure Environment

3. Configure Telegram Session

4. Run the MCP Server

🔌 Connecting to AI Agents

Antigravity CLI (agy)

Claude Desktop

Cursor / Cline / Roo Code / Windsurf

🛠️ MCP Tools Matrix (62 Tools)

🧪 Example Multi-Step Test Scenario

🛡️ Security & Session Protection

🔬 Running Unit Tests

📄 License

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

⚡ Companion Terminal CLI (`tg-cli`)

Antigravity CLI (`agy`)