aiogram-mcp

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.