Which integrations are available for this server?

Provides tools for end-to-end interaction with Telegram bots, including sending commands and messages, clicking inline and reply buttons, running multi-step test suites, sending and downloading media, performing inline queries, managing chats and messages, and verifying bot responses.

How do I use Telegram MCP?

1. Click on "Install 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 Send /start to @MyTestBot and report what it replies." 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 Telegram-mcp

Overview Schema Related Servers Score Discussions

Python

Remote

Telegram MCP 🤖🧪

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.

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.

TIP

Environment Recommendation: We strongly recommend using the Test Server (TELEGRAM_TEST_MODE=true) for bot development and automated testing because it carries zero risk to your main personal Telegram account. Note: Make sure your target bot and user account are on the same environment (Test Server bot ↔ Test Server account, or Prod bot ↔ Prod account), as Telegram test and production networks are completely isolated.

🌟 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: agent-telegram-mcp

🚀 Quickstart

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=false

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

Tool Name	Parameters	Purpose
`telegram_status`	None	Checks connection health, environment, and user info with masked phone for privacy.
`telegram_send_command`	`bot_username`, `command`, `wait_response?`, `timeout_seconds?`	Sends a command and waits for reply.
`telegram_send_message`	`bot_username`, `text`, `reply_to_msg_id?`, `parse_mode?`, `wait_response?`	Sends text payloads or queries with Markdown/HTML formatting.
`telegram_edit_message`	`bot_username`, `message_id`, `new_text`, `parse_mode?`	Edits a previously sent message by ID.
`telegram_delete_messages`	`bot_username`, `message_ids`, `revoke?`	Deletes messages by ID for clean teardown.
`telegram_forward_messages`	`to_chat`, `from_chat`, `message_ids`	Forwards messages from one chat/bot to another.
`telegram_send_reaction`	`bot_username`, `message_id`, `reaction`	Sends an emoji reaction (👍, 🔥, ❤️, etc.) to a message.
`telegram_send_poll`	`bot_username`, `question`, `options`, `is_quiz?`, `correct_option_id?`	Sends native polls or quizzes.
`telegram_mark_chat_read`	`bot_username`, `max_id?`	Marks dialog history as read.
`telegram_list_dialogs`	`limit?`	Lists recent chats, groups, bots, and channels with unread counts.
`telegram_search_messages`	`bot_username`, `query`, `limit?`	Searches message history by text query keyword.
`telegram_click_inline_button`	`bot_username`, `message_id?`, `button_text?`, `button_index?`	Clicks inline buttons and returns updated message state.
`telegram_send_file`	`bot_username`, `file_path`, `caption?`, `voice_note?`	Uploads images/documents/audio (or circular voice notes).
`telegram_download_media`	`bot_username`, `message_id`, `output_dir?`	Downloads media from bot messages.
`telegram_inline_query`	`bot_username`, `query`	Performs inline queries (`@bot query`).
`telegram_send_and_verify`	`bot_username`, `input_text`, `expected_contains`	Convenience single-step assertion.
`telegram_run_test_suite`	`bot_username`, `steps`	Runs multi-step test workflows with `sleep` and assertions.
`telegram_get_bot_info`	`bot_username`	Inspects a bot's description, about text, commands list, and profile metadata.
`telegram_pin_message`	`bot_username`, `message_id`, `notify?`	Pins a message in the chat with the bot or group.
`telegram_unpin_message`	`bot_username`, `message_id?`	Unpins a specific message, or unpins all messages in the chat.
`telegram_get_message_context`	`bot_username`, `message_id`, `limit_before?`, `limit_after?`	Fetches preceding and succeeding messages around a message ID.
`telegram_send_album`	`bot_username`, `file_paths`, `caption?`	Sends multiple photos/files as a grouped album in one message.
`telegram_save_draft`	`bot_username`, `text`, `reply_to_msg_id?`	Saves an uncommitted draft directly into the Telegram chat input box.
`telegram_schedule_message`	`bot_username`, `text`, `schedule_in_seconds?`, `schedule_date_iso?`	Schedules a message for future automated delivery.
`telegram_get_scheduled_messages`	`bot_username`	Retrieves all pending scheduled messages queued in a chat.
`telegram_delete_scheduled_messages`	`bot_username`, `message_ids`	Cancels and deletes scheduled messages before delivery.
`telegram_get_pinned_messages`	`bot_username`, `limit?`	Fetches pinned messages directly from a chat, bot, or channel.
`telegram_mute_chat`	`bot_username`, `duration_seconds?`	Mutes notifications for a specified duration or permanently.
`telegram_unmute_chat`	`bot_username`	Unmutes notifications for a chat or channel.
`telegram_export_chat`	`bot_username`, `limit?`, `format?`	Exports conversation history as clean Markdown or JSON for AI summarization.
`telegram_get_chat_members`	`bot_username`, `limit?`	Lists group/channel participants with names, IDs, and bot flags.
`telegram_get_contacts`	`query?`, `limit?`	Retrieves saved Telegram contacts with privacy-masked phone numbers.
`telegram_resolve_peer`	`peer`	Resolves any username, phone, or ID to detailed entity metadata and type.
`telegram_wait_for`	`bot_username`, `text_contains?`, `after_message_id?`, `target_message_id?`, `wait_for_edit?`, `timeout_seconds?`	Waits for an incoming message, specific substring, or message edit/progress update.
`telegram_get_web_app_url`	`bot_username`, `message_id?`, `button_text?`, `button_index?`	Extracts authenticated Web App launch URLs from Telegram Mini App buttons for frontend testing.
`telegram_click_reply_button`	`bot_username`, `button_text?`, `button_index?`, `wait_response?`	Clicks buttons in persistent bottom reply keyboards and dispatches user actions.
`telegram_send_chat_action`	`bot_username`, `action?`	Broadcasts chat presence indicators ('typing', 'upload_photo', 'record_video', etc.).
`telegram_join_chat`	`chat_identifier`	Joins a public channel/supergroup via @username or private chat via invite link (t.me/+...).
`telegram_leave_chat`	`chat_identifier`	Leaves a channel or group by username or ID.
`telegram_vote_poll`	`bot_username`, `message_id`, `option_index`	Casts a vote on a specific option in a poll or quiz message.
`telegram_retract_vote`	`bot_username`, `message_id`	Retracts a previously submitted poll vote.
`telegram_search_media`	`bot_username`, `media_type?`, `query?`, `limit?`	Searches chat messages filtered by media type ('photo', 'document', 'url', 'video', etc.).
`telegram_send_saved_message`	`text`, `file_path?`	Sends a message or file to your personal Telegram 'Saved Messages' cloud chat (InputPeerSelf).
`telegram_get_saved_messages`	`limit?`	Retrieves recent messages from your personal Telegram 'Saved Messages' cloud chat.
`telegram_download_profile_photo`	`bot_username`, `output_dir?`	Downloads the profile photo or avatar of any user, bot, or group for visual inspection.
`telegram_send_location`	`bot_username`, `latitude`, `longitude`, `title?`, `address?`, `provider?`	Sends geographic coordinates or a named venue to a bot or chat.
`telegram_get_user_profile`	`user_identifier`	Retrieves full profile metadata (about, Telegram Premium, verified, badges).
`telegram_get_participant_permissions`	`chat_identifier`, `user_identifier`	Inspects administrator or restricted permissions of a user or bot in a group/channel.
`telegram_block_peer`	`peer_identifier`	Blocks a user or bot from contacting you.
`telegram_unblock_peer`	`peer_identifier`	Unblocks a previously blocked user or bot.
`telegram_get_blocked_peers`	`limit?`	Retrieves the list of currently blocked users and bots.
`telegram_get_dialog_filters`		Retrieves configured Telegram chat folders/filters (e.g. Work, Bots, Personal) and rule counts.
`telegram_create_dialog_filter`	`title`, `emoticon?`, `filter_id?`, `bots?`, `groups?`, `broadcasts?`	Creates a new Telegram chat folder/filter to organize conversations.
`telegram_delete_dialog_filter`	`filter_id`	Deletes a Telegram chat folder/filter by folder ID.
`telegram_create_chat`	`title`, `about?`, `megagroup?`, `for_forum?`	Creates a new supergroup or broadcast channel for testing workflows or bot integrations.
`telegram_delete_chat`	`chat_identifier`	Permanently deletes a supergroup or channel (must be creator/owner).
`telegram_create_invite_link`	`chat_identifier`, `title?`, `expire_in_seconds?`, `expire_date_iso?`, `usage_limit?`, `request_needed?`	Generates custom invite links with expiration, member limits, and approval gates.
`telegram_execute_code`	`code`, `timeout_seconds?`	Executes arbitrary Python code with live Telethon client access.
`telegram_get_chat_history`	`bot_username`, `limit?`	Fetches recent conversation history.
`telegram_clear_chat`	`bot_username`	Clears conversation dialog for clean tests.

🧪 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"}
]

🔬 Running Unit Tests

Run the test suite locally with pytest or Python's built-in unittest:

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

📄 License

MIT License. See LICENSE for details.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

No tool schema history has been recorded yet.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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
8248
telegram-mcp
io.github.Shreyas-Profile
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Communication App Automation
2
DreamAgent A
io.github.nivethaug
Build and deploy websites, Telegram and Discord bots from chat via the DreamAgent platform.
Coding Agents App Automation Developer Tools
121
DOS AI A
pro.dosai
Run WhatsApp and Telegram AI assistants: projects, prompts, leads, chats, analytics.
Communication Customer Support
131

Related MCP Servers

Telegram MCP Server
Communication Social Media
shaxzodrashid
F
license
A
quality
B
maintenance
Enables AI agents to interact with Telegram via MTProto, supporting high-performance communication and seamless integration.
Updated a month ago (2026-07-23 20:34 UTC)
1
-
agent-telegram-mcp
Communication Social Media
tharindumendis
A
license
A
quality
D
maintenance
Enables AI agents to send and receive messages, media, and files on Telegram, and manage chats via a bot token.
Updated 5 months ago (2026-03-21 22:17 UTC)
17
MIT
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 a day ago (2026-09-04 16:30 UTC)
1
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Telegram-mcp/telegram-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server