send_messageLABSCO SUMMARY
The safety rails are the reason to pick this one.
Most Telegram MCP servers are thin wrappers with a handful of tools and no notion of scope. Here allowed_chat_ids limits which chats an agent can touch at all, permission_level steps from read through messaging and moderation to admin, broadcast is disabled unless you opt in and capped by max_broadcast_recipients, and a token-bucket limiter paces outgoing calls to keep Telegram from returning 429. Combined with the audit log, that is a defensible setup for pointing a model at a bot real people use.
What it is
A layer that runs alongside a working aiogram bot and exposes it to MCP clients. The bot keeps serving Telegram users exactly as before; the MCP server gives an agent tools, resources and pushed events over the same bot. The README puts integration at five lines added to your existing setup.
What you get
- Messaging —
send_message,send_photo,forward_message,delete_message,pin_message - Interactive UI:
send_interactive_messagebuilds inline keyboards,edit_messagechanges text or keyboard in place,answer_callback_queryresponds to a button press with a toast or alert — enough for confirmations and multi-step wizards - Rich media across ten tools including
send_document,send_voice,send_video,send_animation,send_audio,send_sticker,send_locationandsend_poll - Moderation and chat admin —
ban_user,unban_user,set_chat_title,set_chat_description,get_chat_member_info,get_chat_members_count - Push rather than polling:
subscribe_eventsregisters chat and type filters, then events arrive as MCP notifications;unsubscribe_eventsremoves the subscription - Seven read-only resources including
telegram://chatsfor active chats,telegram://chats/{chat_id}/historyfor the last 50 messages,telegram://events/queueand an opt-intelegram://audit/log - Three ready-made prompts:
moderation_promptpulls user info and history before suggesting warn, mute or ban;announcement_promptdrafts a formatted post;user_report_promptcompiles activity - Every tool returns a typed Pydantic model with an
outputSchema, so responses parse programmatically
Requirements
A Telegram bot token from @BotFather, supplied as BOT_TOKEN — server.json marks it required and secret. Python 3.10+ and aiogram 3.20+; pip install aiogram-mcp (version 0.7.1), launched over stdio. Capturing button presses needs dp.callback_query.middleware(middleware) registered alongside the message middleware, or interactive messages will send but never report back. MIT licensed.
Setup effort
Follow the published steps — pip install aiogram-mcp
USE CASES
01
Running an ops bot that alerts a channel
Push incident notices to the chats an agent is allowed to reach, with a rate limiter keeping Telegram from throttling the burst.
02
Getting a decision from a human in Telegram
Send a message with inline buttons, wait for the press to arrive as an event, and edit the same message to reflect the outcome.
03
Moderating a group with context
Pull the user's role and recent history through the moderation prompt, then act — delete, pin, or ban with a duration.
04
Reacting to messages as they arrive
Subscribe with chat and type filters, then handle pushed events instead of polling the queue.
05
Keeping an agent read-only at first
Set the permission level to read so the agent can see bot info, chat info and profiles but cannot send anything.
30 tools
Listed in project docs. Your client may show a different list.
send_photoforward_messagedelete_messagepin_messagesend_interactive_messageedit_messageanswer_callback_queryget_bot_infoget_chat_member_infoget_user_profile_photosget_chat_infoget_chat_members_countban_userunban_userset_chat_titleset_chat_descriptionsend_documentsend_voicesend_videosend_animationsend_audiosend_stickersend_video_notesend_contactsend_locationsend_pollsubscribe_eventsunsubscribe_eventsbroadcastBEFORE YOU INSTALL
What to know first
Tools you get
30 tools named in the project's documentation.
Requires
- python on PATH
- BOT_TOKEN in your environment
INSTALLATION
Connect your client
Server setup
TERMINAL
pip install aiogram-mcpAdd aiogram-mcp to the script that runs your bot: attach MCPMiddleware to the dispatcher for messages and button presses, create AiogramMCP with your bot, dispatcher, middleware and event manager, and start it with mcp.run_alongside_bot(transport="stdio").
MCP Clients
Claude Desktop
Add aiogram-mcp to your bot
The README's Quickstart lines, added to the script that runs your aiogram bot. Put your bot's token from @BotFather where it says <YOUR_TOKEN>.
CLAUDE DESKTOP
import asyncio
from aiogram import Bot, Dispatcher
from aiogram_mcp import AiogramMCP, EventManager, MCPMiddleware
bot = Bot(token="<YOUR_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())Point Claude Desktop at that script
<YOUR_PATH_TO_BOT> is the full path of that script, and <YOUR_BOT_TOKEN> is the same bot token.
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"my-telegram-bot": {
"command": "python",
"args": [
"<YOUR_PATH_TO_BOT>"
],
"env": {
"BOT_TOKEN": "<YOUR_BOT_TOKEN>"
}
}
}
}
