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 `outputSchema` for programmatic parsing
• Real-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

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-mcp

Requires 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)

Interactive Messages (3 tools)

Users (3 tools)

Chats (6 tools)

Rich Media (10 tools)

Events (2 tools)

Broadcast (1 tool, opt-in)

MCP Resources

Read-only data that AI agents can access without calling tools:

MCP Prompts

Pre-built workflows that give AI agents structured context:

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/queue

The 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
)

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

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 mode

License

MIT. See LICENSE.