aiogram-mcp server

by Py2755·io.github.Py2755/aiogram-mcp·v0.7.1·3 stars

No reviews yet

MCP server for aiogram Telegram bots — 30 tools, 7 resources, 3 prompts, event streaming

C66/100grade C

Write a review Install

What users say

No reviews yet

Be the first

Safety scan

C66/100

full report

Adoption

New

3 stars38 downloads/wk

Reviews

Write one

Nobody has reviewed aiogram-mcp yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

aiogram-mcp tools (30, 15 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

answer_callback_query
Answer a callback query from an inline keyboard button press.
ban_user
Ban a user from a chat.
broadcastwrite action
Send a message to multiple users or chats.
delete_messagewrite action
Delete a message from a chat.
edit_message
Edit the text and/or inline keyboard of an existing message.
forward_message
Forward an existing message from one chat to another.
get_bot_info
Return metadata about the current Telegram bot.
get_chat_info
Get details about a chat.
get_chat_member_info
Return role and user info for a chat member.
get_chat_members_count
Get the number of members in a chat.
get_user_profile_photos
Return a lightweight list of Telegram profile photo file IDs.
pin_message
Pin a message in a chat.
send_animationwrite action
Send a GIF/animation to a Telegram chat.
send_audiowrite action
Send an audio file (music) to a Telegram chat.
send_contactwrite action
Send a phone contact to a Telegram chat.
send_documentwrite action
Send a document/file to a Telegram chat.
send_interactive_messagewrite action
Send a message with inline keyboard buttons.
send_locationwrite action
Send a location to a Telegram chat.
send_messagewrite action
Send a text message to a Telegram chat or user.
send_photowrite action
Send a photo to a Telegram chat.
send_pollwrite action
Send a poll to a Telegram chat.
send_stickerwrite action
Send a sticker to a Telegram chat.
send_videowrite action
Send a video to a Telegram chat.
send_video_notewrite action
Send a video note (round video) to a Telegram chat.
send_voicewrite action
Send a voice message to a Telegram chat.
set_chat_description
Change the description of a group or channel.
set_chat_title
Change the title of a group or channel.
subscribe_events
Subscribe to real-time Telegram events.
unban_user
Unban a previously banned user.
unsubscribe_events
Unsubscribe from real-time Telegram events.

Public scan report

scanner v0.1.10 · 2026-09-27 · same rubric, same numbers if you re-run it

no findings

Code scan22 source files scanned25/25
–Live reliabilityno gateway calls yet and no remote to proben/a
–Tool poisoningtools not inspected (local package is not executed); not countedn/a
Auth qualitystatic API keys via environment variables6/15
Maintenancelast push 196 days ago4/15
Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Overall 66/100. Components that don't apply are left out of the denominator. Any critical finding is an F.Rubric Appeal a finding JSON

How aiogram-mcp compares

Against every graded MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score: 66/100; higher than 23% of 48,255 servers
Tools: 30; the typical server has 7
Tools that change things: 50%; typical: 0%. Fewer write tools means less an agent can break
GitHub stars: 3; more than 80% of 28,688 servers
Downloads a week: 38; more than 29% of 12,191 servers with a package

What its tools let an agent do: 11 read · 3 change · 2 delete · 14 send or post

Install aiogram-mcp in Claude Code, Cursor or VS Code

claude mcp add aiogram-mcp -- uvx aiogram-mcp

Add to Cursor

What the publisher says

From the aiogram-mcp repository's README, as published. We do not edit it. Read it on GitHub

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

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

aiogram-mcp: common questions

Is aiogram-mcp server safe?: With care: it is graded C, so read the findings first (66/100). Read the aiogram-mcp safety report
How do I install aiogram-mcp?: It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does aiogram-mcp need an API key?: Yes. The registry entry asks for BOT_TOKEN.
Is aiogram-mcp maintained?: The last commit was 233 days ago (2026-03-16). The latest release is v0.7.1.
How does aiogram-mcp compare with other MCP servers?: safety score 66/100 (higher than 23% of 48,255 servers); tools 30 (the typical server has 7); tools that change things 50% (typical: 0%. Fewer write tools means less an agent can break). Full comparison.