A
licenseB
qualityD
maintenanceFull-featured Telegram Bot API server for MCP (Model Context Protocol). 174 tools covering the entire Bot API — messages, chats, stickers, payments, forums, stories, and more.
100
334 npm
7
MIT
aiogram-mcp
by Py2755
aiogram-mcp is an MCP server that connects AI agents (like Claude) to a Telegram bot, enabling comprehensive bot management, messaging, moderation, and real-time event monitoring.
Messaging & Media
Send text messages with HTML/Markdown formatting, reply threading, and silent delivery
Send photos, documents, voice messages, videos, animations/GIFs, audio, stickers, video notes, contacts, locations, and polls
Forward, delete, and pin messages
Interactive Messages
Create messages with inline keyboard buttons (callback or URL)
Edit existing messages and keyboards
Answer callback queries with toast notifications or alert popups
User & Chat Management
Retrieve bot metadata, chat info (title, type, description, member count), and user profile info/photos
Ban/unban users, modify chat titles and descriptions
Real-Time Events
Subscribe/unsubscribe to Telegram events (messages, commands, callback queries) with chat and type filters, receiving real-time push notifications
Safety & Control
Built-in rate limiting, fine-grained permission levels (read, messaging, moderation, admin), chat access restrictions, and opt-in broadcasting with safety limits
Audit logging of all tool invocations with timestamps and arguments
Resources & Workflows
Read-only access to bot info, configuration, chat lists, message history, event queues, file metadata, and audit logs
Pre-built prompts for moderation, announcements, and user activity reports
Turns an aiogram-based Telegram bot into an MCP server, enabling AI agents to send messages and rich media, manage chat history, moderate users, handle interactive inline keyboards, and subscribe to real-time bot events.
aiogram-mcp
Connect your Telegram bot to AI agents via the Model Context Protocol.
aiogram-mcp turns any aiogram bot into an MCP server. AI clients like Claude Desktop can then send messages, read chat history, build interactive menus, and react to events in real time — all through your existing bot, without rewriting a single handler.
Why aiogram-mcp?
Most Telegram MCP servers are thin wrappers with 3-5 tools. aiogram-mcp goes further:
30 tools — messaging, rich media, moderation, interactive keyboards, event subscriptions, broadcasting
7 resources — bot info, config, chat lists, message history, event queue, file metadata, audit log
3 prompts — ready-made moderation, announcement, and user report workflows
Structured output — every tool returns typed Pydantic models with
outputSchemafor programmatic parsingReal-time events — the bot pushes Telegram events to AI clients via MCP notifications (no polling)
Interactive messages — AI agents create inline keyboard menus, handle button presses, edit messages
Rate limiting — built-in token bucket prevents Telegram 429 errors
Permission levels — restrict AI agents to read-only, messaging, moderation, or full admin access
Audit logging — track every tool invocation with timestamps and arguments
Zero rewrite — add 5 lines to your existing bot, keep all your handlers
Related MCP server: Straight Connect
How It Works
Telegram users Your aiogram bot AI agent (Claude Desktop)
| | |
| send messages, tap buttons | |
| --------------------------> | |
| | MCP server (stdio or SSE) |
| | <-------------------------> |
| | tools / resources / events |
| | |
| bot replies, shows menus | send_message, edit, ban |
| <-------------------------- | <--------------------------- |The bot runs normally for Telegram users. The MCP server runs alongside it, giving AI agents access to the same bot via tools and resources.
Installation
pip install aiogram-mcpRequires Python 3.10+ and aiogram 3.20+.
Quickstart
1. Add aiogram-mcp to your bot
import asyncio
from aiogram import Bot, Dispatcher
from aiogram_mcp import AiogramMCP, EventManager, MCPMiddleware
bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()
# Middleware tracks chats, users, message history, and events
event_manager = EventManager()
middleware = MCPMiddleware(event_manager=event_manager)
dp.message.middleware(middleware)
dp.callback_query.middleware(middleware) # for interactive buttons
# Register your normal handlers here
# @dp.message(...)
# async def my_handler(message): ...
# Create the MCP server
mcp = AiogramMCP(
bot=bot,
dp=dp,
name="my-bot",
middleware=middleware,
event_manager=event_manager,
allowed_chat_ids=[123456789], # optional: restrict which chats AI can access
)
async def main():
await mcp.run_alongside_bot(transport="stdio")
asyncio.run(main())2. Connect Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"my-telegram-bot": {
"command": "python",
"args": ["path/to/your/bot.py"],
"env": {
"BOT_TOKEN": "123456:ABC-DEF..."
}
}
}
}Now Claude can send messages, read history, create button menus, and react to events in your Telegram bot.
Built-in Tools
Messaging (5 tools)
Tool | Description |
| Send text with HTML/Markdown formatting |
| Send a photo by URL with optional caption |
| Forward a message between chats |
| Delete a message |
| Pin a message in a chat |
Interactive Messages (3 tools)
Tool | Description |
| Send a message with inline keyboard buttons (callback or URL) |
| Edit text and/or keyboard of an existing message |
| Respond to a button press with a toast or alert |
Users (3 tools)
Tool | Description |
| Get bot metadata (username, capabilities) |
| Get a user's role and profile in a chat |
| Get a user's profile photos |
Chats (6 tools)
Tool | Description |
| Get chat metadata (title, type, description) |
| Get number of members in a chat |
| Ban a user (permanent or temporary) |
| Unban a user |
| Change the chat title |
| Change the chat description |
Rich Media (10 tools)
Tool | Description |
| Send a file/document by URL with optional caption |
| Send a voice message by URL |
| Send a video by URL with optional caption |
| Send a GIF/animation by URL |
| Send audio/music by URL with performer and title |
| Send a sticker by file_id or URL |
| Send a round video note by URL |
| Send a contact with phone number and name |
| Send a geolocation pin |
| Create a poll with multiple options |
Events (2 tools)
Tool | Description |
| Subscribe to real-time events with chat/type filters |
| Remove a subscription |
Broadcast (1 tool, opt-in)
Tool | Description |
| Send a message to multiple chats (requires |
MCP Resources
Read-only data that AI agents can access without calling tools:
URI | Description |
| Bot username, ID, and capabilities |
| Server name and allowed chat IDs |
| List of active chats with metadata |
| Last 50 messages in a chat |
| Event queue with auto-incrementing IDs |
| File metadata (size, path, unique ID) |
| Audit log of tool invocations (opt-in) |
MCP Prompts
Pre-built workflows that give AI agents structured context:
Prompt | Arguments | What it does |
|
| Fetches user info + message history, suggests warn/mute/ban |
|
| Drafts a formatted Telegram announcement |
|
| Compiles a full user activity report |
Real-time Event Streaming
AI agents don't need to poll. The bot pushes events automatically:
Telegram message arrives
→ MCPMiddleware captures it
→ EventManager stores it (type: "message", "command", or "callback_query")
→ MCP notification sent to subscribed clients
→ AI agent reads telegram://events/queueThe AI agent calls subscribe_events once, then receives push notifications whenever new events match its filters.
Interactive Messages
AI agents can build full interactive UIs in Telegram — menus, confirmations, multi-step wizards:
The AI agent sends a message with buttons:
┌─────────────────────────┐
│ Confirm deployment? │
│ │
│ [✅ Yes] [❌ No] │
│ [📖 View docs] │
└─────────────────────────┘User taps a button → event appears in the queue → AI agent reacts:
┌─────────────────────────┐
│ ✅ Deployed! │
│ │
│ [📋 View logs] │
└─────────────────────────┘The bot needs dp.callback_query.middleware(middleware) to capture button presses.
Safety Controls
mcp = AiogramMCP(
bot=bot,
dp=dp,
allowed_chat_ids=[123456789, -1001234567890], # restrict AI access
enable_broadcast=True, # opt-in for broadcast tool
max_broadcast_recipients=500, # safety limit
)allowed_chat_ids— AI can only interact with listed chats. Default: all chats.enable_broadcast— broadcast tool is disabled by default as a safety measure.max_broadcast_recipients— caps the number of chats in a single broadcast.
Advanced Configuration
Rate Limiting
mcp = AiogramMCP(
bot=bot, dp=dp,
rate_limit=30, # requests/sec (default), 0 to disable
)Built-in token bucket rate limiter prevents Telegram 429 errors. All outgoing API calls are automatically paced.
Permission Levels
mcp = AiogramMCP(
bot=bot, dp=dp,
permission_level="messaging", # read + messaging tools only
)Level | Access |
| Bot info, chat info, user profiles |
| Read + send messages, photos, media, interactive messages |
| Messaging + delete, pin, ban, unban, chat settings |
| Full access including broadcast and event subscriptions |
Audit Log
mcp = AiogramMCP(
bot=bot, dp=dp,
enable_audit=True,
audit_log_size=1000,
)Every tool invocation is logged. Access via telegram://audit/log resource.
Examples
Example | Transport | Features |
stdio | Full setup with middleware, events, and callback tracking | |
SSE | Broadcast-enabled ops bot for incident notifications |
Development
git clone https://github.com/Py2755/aiogram-mcp.git
cd aiogram-mcp
pip install -e ".[dev]"
pytest -v # ~228 tests
ruff check aiogram_mcp tests examples
mypy aiogram_mcp # strict modeLicense
MIT. See LICENSE.
Available Tools
29 toolsanswer_callback_queryB
Answer a callback query from an inline keyboard button press.
Inputs: callback_query_id (required), text, show_alert. Returns: ok, error, callback_query_id
ban_userC
Ban a user from a chat.
Inputs: chat_id (required), user_id (required), ban_duration_hours, revoke_messages. Returns: ok, error, user_id, permanent, +1 more
delete_messageC
Delete a message from a chat.
Inputs: chat_id (required), message_id (required). Returns: Result for tools that return only ok/error (delete, pin, etc.).
edit_messageA
Edit the text and/or inline keyboard of an existing message.
Inputs: chat_id (required), message_id (required), text (required), buttons, +1 more. Returns: ok, error, message_id, chat_id
forward_messageC
Forward an existing message from one chat to another.
Inputs: to_chat_id (required), from_chat_id (required), message_id (required), disable_notification. Returns: ok, error, message_id
get_bot_infoA
Return metadata about the current Telegram bot.
Inputs: no named parameters. Returns: ok, error, id, username, +5 more
get_chat_infoC
Get details about a chat.
Inputs: chat_id (required). Returns: ok, error, id, type, +5 more
get_chat_member_infoB
Return role and user info for a chat member.
Inputs: chat_id (required), user_id (required). Returns: ok, error, chat_id, user_id, +6 more
get_chat_members_countB
Get the number of members in a chat.
Inputs: chat_id (required). Returns: ok, error, count
get_user_profile_photosC
Return a lightweight list of Telegram profile photo file IDs.
Inputs: user_id (required), limit. Returns: ok, error, user_id, total_count, +1 more
pin_messageC
Pin a message in a chat.
Inputs: chat_id (required), message_id (required), disable_notification. Returns: Result for tools that return only ok/error (delete, pin, etc.).
send_animationC
Send a GIF/animation to a Telegram chat.
Inputs: chat_id (required), animation_url (required), caption, parse_mode, +1 more. Returns: ok, error, message_id, chat_id
send_audioB
Send an audio file (music) to a Telegram chat.
Inputs: chat_id (required), audio_url (required), caption, parse_mode, +3 more. Returns: ok, error, message_id, chat_id
send_contactB
Send a phone contact to a Telegram chat.
Inputs: chat_id (required), phone_number (required), first_name (required), last_name, +1 more. Returns: ok, error, message_id, chat_id
send_documentB
Send a document/file to a Telegram chat.
Inputs: chat_id (required), document_url (required), caption, parse_mode, +1 more. Returns: ok, error, message_id, chat_id
send_interactive_messageB
Send a message with inline keyboard buttons.
Inputs: chat_id (required), text (required), buttons (required), parse_mode, +1 more. Returns: ok, error, message_id, chat_id, +1 more
send_locationB
Send a location to a Telegram chat.
Inputs: chat_id (required), latitude (required), longitude (required), disable_notification. Returns: ok, error, message_id, chat_id
send_messageC
Send a text message to a Telegram chat or user.
Inputs: chat_id (required), text (required), parse_mode, disable_notification, +1 more. Returns: ok, error, message_id, chat_id, +1 more
send_photoC
Send a photo to a Telegram chat.
Inputs: chat_id (required), photo_url (required), caption, parse_mode, +1 more. Returns: ok, error, message_id, chat_id
send_pollC
Send a poll to a Telegram chat.
Inputs: chat_id (required), question (required), options (required), is_anonymous, +3 more. Returns: ok, error, message_id, chat_id, +1 more
send_stickerC
Send a sticker to a Telegram chat.
Inputs: chat_id (required), sticker (required), disable_notification. Returns: ok, error, message_id, chat_id
send_videoB
Send a video to a Telegram chat.
Inputs: chat_id (required), video_url (required), caption, parse_mode, +2 more. Returns: ok, error, message_id, chat_id
send_video_noteB
Send a video note (round video) to a Telegram chat.
Inputs: chat_id (required), video_note_url (required), duration, length, +1 more. Returns: ok, error, message_id, chat_id
send_voiceB
Send a voice message to a Telegram chat.
Inputs: chat_id (required), voice_url (required), caption, parse_mode, +2 more. Returns: ok, error, message_id, chat_id
set_chat_descriptionB
Change the description of a group or channel.
Inputs: chat_id (required), description (required). Returns: Result for tools that return only ok/error (delete, pin, etc.).
set_chat_titleC
Change the title of a group or channel.
Inputs: chat_id (required), title (required). Returns: ok, error, new_title
subscribe_eventsA
Subscribe to real-time Telegram events.
Receive notifications when new events match your filters. Read the telegram://events/queue resource to get event data.
Inputs: chat_ids, event_types. Returns: ok, error, subscription_id, chat_ids, +2 more
unban_userC
Unban a previously banned user.
Inputs: chat_id (required), user_id (required), only_if_banned. Returns: ok, error, user_id
unsubscribe_eventsC
Unsubscribe from real-time Telegram events.
Inputs: subscription_id (required). Returns: ok, error, subscription_id
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
B3.3/5.0
Scored across 29 tools
Disambiguation5/5
Each tool targets a distinct action or resource, with no overlaps. Send methods are clearly differentiated by media type, and administrative actions like ban/unban/pin are separate.
Naming Consistency5/5
All tools follow a verb_noun pattern in snake_case, e.g., send_message, get_chat_info, answer_callback_query. There are no deviations or mixed conventions.
Tool Count4/5
29 tools is high but justified by the breadth of Telegram Bot API. It covers common operations without being excessive, though a few niche actions could be added.
Completeness4/5
The set covers core CRUD for messages, chats, members, and media, plus events. Missing some advanced features like stop_poll or leave_chat, but overall sufficient for typical bot interactions.
Maintenance
ActivityInactive
ResponsivenessLimited data
Related MCP Connectors
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Zero-log MCP server with 49 tools for AI guardrails, secret scanning, MCP linting & EU compliance.
491MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server for communication service connectors that currently provides multi-account Telegram integration with granular tool access and security controls. It allows AI models to manage messages, chats, and media across various accounts through a flexible, extensible routing architecture.1-
- AlicenseAqualityDmaintenanceA comprehensive MCP server providing 35 tools for managing Telegram messages, media, and chat interactions via the Bot API. It also features a real-time monitoring system using the Telethon User API to log messages from specific channels.35Apache 2.0
- AlicenseCqualityCmaintenanceUltimate MCP server for Telegram Bot API — 169 methods, full v9.6 coverage, meta-mode, rate limiting, and circuit breaker, enabling AI to control Telegram bots with natural language.10034MIT