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.
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.
- Messaging — `send_message`, `send_photo`, `forward_message`, `delete_message`, `pin_message`
- Interactive UI: `send_interactive_message` builds inline keyboards, `edit_message` changes text or keyboard in place, `answer_callback_query` responds 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_location` and `send_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_events` registers chat and type filters, then events arrive as MCP notifications; `unsubscribe_events` removes the subscription
- Seven read-only resources including `telegram://chats` for active chats, `telegram://chats/{chat_id}/history` for the last 50 messages, `telegram://events/queue` and an opt-in `telegram://audit/log`
- Three ready-made prompts: `moderation_prompt` pulls user info and history before suggesting warn, mute or ban; `announcement_prompt` drafts a formatted post; `user_report_prompt` compiles activity
- Every tool returns a typed Pydantic model with an `outputSchema`, so responses parse programmatically
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` (0.7.1 in pyproject and server.json), 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.
One command plus a key — pip install aiogram-mcp, then supply credentials