{
  "markdown": "# aiogram-mcp\n\n[![CI](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Py2755/aiogram-mcp/actions/workflows/ci.yml)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![PyPI version](https://img.shields.io/pypi/v/aiogram-mcp.svg)](https://pypi.org/project/aiogram-mcp/)\n[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/)\n\n<!-- mcp-name: io.github.Py2755/aiogram-mcp -->\n\n**Connect your Telegram bot to AI agents via the Model Context Protocol.**\n\n`aiogram-mcp` turns any [aiogram](https://github.com/aiogram/aiogram) bot into an [MCP](https://modelcontextprotocol.io/) 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.\n\n## Why aiogram-mcp?\n\nMost Telegram MCP servers are thin wrappers with 3-5 tools. `aiogram-mcp` goes further:\n\n- **30 tools** — messaging, rich media, moderation, interactive keyboards, event subscriptions, broadcasting\n- **7 resources** — bot info, config, chat lists, message history, event queue, file metadata, audit log\n- **3 prompts** — ready-made moderation, announcement, and user report workflows\n- **Structured output** — every tool returns typed Pydantic models with `outputSchema` for programmatic parsing\n- **Real-time events** — the bot pushes Telegram events to AI clients via MCP notifications (no polling)\n- **Interactive messages** — AI agents create inline keyboard menus, handle button presses, edit messages\n- **Rate limiting** — built-in token bucket prevents Telegram 429 errors\n- **Permission levels** — restrict AI agents to read-only, messaging, moderation, or full admin access\n- **Audit logging** — track every tool invocation with timestamps and arguments\n- **Zero rewrite** — add 5 lines to your existing bot, keep all your handlers\n\n## How It Works\n\n```\nTelegram users                Your aiogram bot              AI agent (Claude Desktop)\n      |                             |                              |\n      |  send messages, tap buttons |                              |\n      | --------------------------> |                              |\n      |                             |  MCP server (stdio or SSE)   |\n      |                             | <------------------------->  |\n      |                             |  tools / resources / events  |\n      |                             |                              |\n      |  bot replies, shows menus   |   send_message, edit, ban    |\n      | <-------------------------- | <--------------------------- |\n```\n\nThe bot runs normally for Telegram users. The MCP server runs alongside it, giving AI agents access to the same bot via tools and resources.\n\n## Installation\n\n```bash\npip install aiogram-mcp\n```\n\nRequires Python 3.10+ and aiogram 3.20+.\n\n## Quickstart\n\n### 1. Add aiogram-mcp to your bot\n\n```python\nimport asyncio\nfrom aiogram import Bot, Dispatcher\nfrom aiogram_mcp import AiogramMCP, EventManager, MCPMiddleware\n\nbot = Bot(token=\"YOUR_BOT_TOKEN\")\ndp = Dispatcher()\n\n# Middleware tracks chats, users, message history, and events\nevent_manager = EventManager()\nmiddleware = MCPMiddleware(event_manager=event_manager)\ndp.message.middleware(middleware)\ndp.callback_query.middleware(middleware)  # for interactive buttons\n\n# Register your normal handlers here\n# @dp.message(...)\n# async def my_handler(message): ...\n\n# Create the MCP server\nmcp = AiogramMCP(\n    bot=bot,\n    dp=dp,\n    name=\"my-bot\",\n    middleware=middleware,\n    event_manager=event_manager,\n    allowed_chat_ids=[123456789],  # optional: restrict which chats AI can access\n)\n\nasync def main():\n    await mcp.run_alongside_bot(transport=\"stdio\")\n\nasyncio.run(main())\n```\n\n### 2. Connect Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"my-telegram-bot\": {\n      \"command\": \"python\",\n      \"args\": [\"path/to/your/bot.py\"],\n      \"env\": {\n        \"BOT_TOKEN\": \"123456:ABC-DEF...\"\n      }\n    }\n  }\n}\n```\n\nNow Claude can send messages, read history, create button menus, and react to events in your Telegram bot.\n\n## Built-in Tools\n\n### Messaging (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `send_message` | Send text with HTML/Markdown formatting |\n| `send_photo` | Send a photo by URL with optional caption |\n| `forward_message` | Forward a message between chats |\n| `delete_message` | Delete a message |\n| `pin_message` | Pin a message in a chat |\n\n### Interactive Messages (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `send_interactive_message` | Send a message with inline keyboard buttons (callback or URL) |\n| `edit_message` | Edit text and/or keyboard of an existing message |\n| `answer_callback_query` | Respond to a button press with a toast or alert |\n\n### Users (3 tools)\n\n| Tool | Description |\n|------|-------------|\n| `get_bot_info` | Get bot metadata (username, capabilities) |\n| `get_chat_member_info` | Get a user's role and profile in a chat |\n| `get_user_profile_photos` | Get a user's profile photos |\n\n### Chats (6 tools)\n\n| Tool | Description |\n|------|-------------|\n| `get_chat_info` | Get chat metadata (title, type, description) |\n| `get_chat_members_count` | Get number of members in a chat |\n| `ban_user` | Ban a user (permanent or temporary) |\n| `unban_user` | Unban a user |\n| `set_chat_title` | Change the chat title |\n| `set_chat_description` | Change the chat description |\n\n### Rich Media (10 tools)\n\n| Tool | Description |\n|------|-------------|\n| `send_document` | Send a file/document by URL with optional caption |\n| `send_voice` | Send a voice message by URL |\n| `send_video` | Send a video by URL with optional caption |\n| `send_animation` | Send a GIF/animation by URL |\n| `send_audio` | Send audio/music by URL with performer and title |\n| `send_sticker` | Send a sticker by file_id or URL |\n| `send_video_note` | Send a round video note by URL |\n| `send_contact` | Send a contact with phone number and name |\n| `send_location` | Send a geolocation pin |\n| `send_poll` | Create a poll with multiple options |\n\n### Events (2 tools)\n\n| Tool | Description |\n|------|-------------|\n| `subscribe_events` | Subscribe to real-time events with chat/type filters |\n| `unsubscribe_events` | Remove a subscription |\n\n### Broadcast (1 tool, opt-in)\n\n| Tool | Description |\n|------|-------------|\n| `broadcast` | Send a message to multiple chats (requires `enable_broadcast=True`) |\n\n## MCP Resources\n\nRead-only data that AI agents can access without calling tools:\n\n| URI | Description |\n|-----|-------------|\n| `telegram://bot/info` | Bot username, ID, and capabilities |\n| `telegram://config` | Server name and allowed chat IDs |\n| `telegram://chats` | List of active chats with metadata |\n| `telegram://chats/{chat_id}/history` | Last 50 messages in a chat |\n| `telegram://events/queue` | Event queue with auto-incrementing IDs |\n| `telegram://files/{file_id}` | File metadata (size, path, unique ID) |\n| `telegram://audit/log` | Audit log of tool invocations (opt-in) |\n\n## MCP Prompts\n\nPre-built workflows that give AI agents structured context:\n\n| Prompt | Arguments | What it does |\n|--------|-----------|-------------|\n| `moderation_prompt` | `chat_id`, `user_id`, `reason` | Fetches user info + message history, suggests warn/mute/ban |\n| `announcement_prompt` | `topic`, `audience?`, `tone?` | Drafts a formatted Telegram announcement |\n| `user_report_prompt` | `chat_id`, `user_id` | Compiles a full user activity report |\n\n## Real-time Event Streaming\n\nAI agents don't need to poll. The bot pushes events automatically:\n\n```\nTelegram message arrives\n    → MCPMiddleware captures it\n        → EventManager stores it (type: \"message\", \"command\", or \"callback_query\")\n            → MCP notification sent to subscribed clients\n                → AI agent reads telegram://events/queue\n```\n\nThe AI agent calls `subscribe_events` once, then receives push notifications whenever new events match its filters.\n\n## Interactive Messages\n\nAI agents can build full interactive UIs in Telegram — menus, confirmations, multi-step wizards:\n\n**The AI agent sends a message with buttons:**\n```\n┌─────────────────────────┐\n│ Confirm deployment?     │\n│                         │\n│  [✅ Yes]  [❌ No]      │\n│  [📖 View docs]        │\n└─────────────────────────┘\n```\n\n**User taps a button → event appears in the queue → AI agent reacts:**\n```\n┌─────────────────────────┐\n│ ✅ Deployed!            │\n│                         │\n│  [📋 View logs]        │\n└─────────────────────────┘\n```\n\nThe bot needs `dp.callback_query.middleware(middleware)` to capture button presses.\n\n## Safety Controls\n\n```python\nmcp = AiogramMCP(\n    bot=bot,\n    dp=dp,\n    allowed_chat_ids=[123456789, -1001234567890],  # restrict AI access\n    enable_broadcast=True,            # opt-in for broadcast tool\n    max_broadcast_recipients=500,     # safety limit\n)\n```\n\n- **`allowed_chat_ids`** — AI can only interact with listed chats. Default: all chats.\n- **`enable_broadcast`** — broadcast tool is disabled by default as a safety measure.\n- **`max_broadcast_recipients`** — caps the number of chats in a single broadcast.\n\n## Advanced Configuration\n\n### Rate Limiting\n\n```python\nmcp = AiogramMCP(\n    bot=bot, dp=dp,\n    rate_limit=30,  # requests/sec (default), 0 to disable\n)\n```\n\nBuilt-in token bucket rate limiter prevents Telegram 429 errors. All outgoing API calls are automatically paced.\n\n### Permission Levels\n\n```python\nmcp = AiogramMCP(\n    bot=bot, dp=dp,\n    permission_level=\"messaging\",  # read + messaging tools only\n)\n```\n\n| Level | Access |\n|-------|--------|\n| `read` | Bot info, chat info, user profiles |\n| `messaging` | Read + send messages, photos, media, interactive messages |\n| `moderation` | Messaging + delete, pin, ban, unban, chat settings |\n| `admin` | Full access including broadcast and event subscriptions |\n\n### Audit Log\n\n```python\nmcp = AiogramMCP(\n    bot=bot, dp=dp,\n    enable_audit=True,\n    audit_log_size=1000,\n)\n```\n\nEvery tool invocation is logged. Access via `telegram://audit/log` resource.\n\n## Examples\n\n| Example | Transport | Features |\n|---------|-----------|----------|\n| [basic_bot.py](examples/basic_bot.py) | stdio | Full setup with middleware, events, and callback tracking |\n| [incident_alert_bot.py](examples/incident_alert_bot.py) | SSE | Broadcast-enabled ops bot for incident notifications |\n\n## Development\n\n```bash\ngit clone https://github.com/Py2755/aiogram-mcp.git\ncd aiogram-mcp\npip install -e \".[dev]\"\n\npytest -v          # ~228 tests\nruff check aiogram_mcp tests examples\nmypy aiogram_mcp   # strict mode\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 10865,
  "sha": "c21a67d6eb37cec618d90ad1e3fe5b4a4172c6db2cfc70d7ee5ca1cf5a7ab05b",
  "repo_slug": "py2755/aiogram-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_py2755_aiogram_mcp_a4290f36/readme"
}