Which integrations are available for this server?

Provides tools for AI agents to interact with Telegram bots end-to-end, including sending commands and messages, clicking inline and reply buttons, testing bot workflows, exchanging media/files, performing inline queries, and running multi-step test suites.

How do I use telegram-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@telegram-mcp Test @my_test_bot: send /start, click the inline button, and verify the reply." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

telegram-mcp

by Fire162

Overview Schema Source Related Servers Discussions Admin

Python

Remote

🤖 Telegram MCP

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

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

Related MCP server: telegram-bot-testing-mcp

🌟 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)

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.

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.).

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.

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.

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.

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.

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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

fast-mcp-telegram A
io.github.leshchenko1979
Multi-tenant Telegram gateway for AI agents — HTTP+stdio, 8 tools, MTProto User API
Communication
8249
telegram-mcp
io.github.Shreyas-Profile
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Communication App Automation
2
openhelmOAuth
ai.openhelm
Autonomous cloud agent tasks: real browser + your tools, structured evidence-backed results.
Agent Orchestration Browser Automation Autonomous Agents
2
aiqaramba
io.github.ajrogier
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Testing & QA Tools Browser Automation Agent Orchestration
2

Related MCP Servers

Telegram MCP Server
Communication Social Media
shaxzodrashid
F
license
A
quality
D
maintenance
Enables AI agents to interact with Telegram via MTProto, supporting high-performance communication and seamless integration.
Updated 2 months ago (2026-07-23 20:34 UTC)
1
-
telegram-bot-testing-mcp
Testing & QA Tools Browser Automation Communication
0x216
A
license
Not graded
quality
B
maintenance
Enables AI agents to test Telegram bots by driving the official Telegram Web client in a real browser, allowing visual verification of bot responses, inline keyboards, and Mini Apps.
Updated 2 months ago (2026-07-14 12:25 UTC)
2
MIT
tgx
Communication Social Media
mal4i6ka
A
license
Not graded
quality
A
maintenance
Enables AI agents to operate a Telegram account through the same commands as the terminal client: messaging, chat management, voice transcription, calls, stickers, and privacy settings.
Updated 19 days ago (2026-09-04 16:30 UTC)
1
MIT
Telegram Bot Testing &
Testing & QA Tools Communication
Fire162
A
license
Not graded
quality
B
maintenance
Enables AI coding agents to autonomously interact with, test, click inline buttons on, and verify Telegram bots end-to-end via MTProto.
Updated 24 days ago (2026-08-30 10:13 UTC)
MIT