aiogram-mcp

Connect your Telegram bot to AI agents via the Model Context Protocol.

aiogram-mcpturns anyaiogrambot into anMCPserver. 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.

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

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

Add to yourclaude_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.

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

Pre-built workflows that give AI agents structured context:

AI agents don't need to poll. The bot pushes events automatically:

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 needsdp.callback_query.middleware(middleware)to capture button presses.

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.

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.

mcp = AiogramMCP( bot=bot, dp=dp, permission_level="messaging", # read + messaging tools only )

mcp = AiogramMCP( bot=bot, dp=dp, enable_audit=True, audit_log_size=1000, )

Every tool invocation is logged. Access viatelegram://audit/logresource.

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

Production-grade MCP server for Telegram with dual-mode Bot API + MTProto, 6 composite tools

Build, edit, and deploy Telegram bots on FlowCastle's hosted visual flow platform.

Read-only public stats for Telegram groups tracked by Limzo — activity, engagement, mood and leaderboards, no API key required.

Telegram MCP server with 20 tools — read chats, search messages, download media via MTProto

A simple gateway to interact with Telegram bots using MCP and a REST API, enabling integration with LLMs.

MCTL for Telegram lets users access and manage their own Telegram account from ChatGPT after explicit user authorization. It supports reading recent chats, summarizing messages, drafting replies, preview-only sending by default, confirmed pin actions, audit review, and account disconnect/delete controls. It is not an official Telegram app or Telegram API partner, and Telegram message content is treated as untrusted user-generated data.

Manage your WhatsApp, SMS and Phone Calls using a single MCP connector

Connect to any function, any language, across network boundaries using AgentRPC.

Access your meeting transcripts, summaries, and action items from any AI assistant.