aiogram-mcp

aiogram-mcp

Model Context Protocol を通じて、Telegram ボットを AI エージェントに接続します。

aiogram-mcp を使うと、あらゆる aiogram ボットを MCP サーバーにできます。Claude Desktop などの AI クライアントは、既存のボットを通じてメッセージの送信、チャット履歴の読み取り、インタラクティブメニューの作成、リアルタイムでのイベントへの応答を行えます。ハンドラーを書き直す必要はありません。

aiogram-mcp を選ぶ理由

多くの Telegram MCP サーバーは、3～5 個のツールを備えた薄いラッパーにすぎません。aiogram-mcp はそれ以上の機能を提供します。

• 30 個のツール — メッセージング、リッチメディア、モデレーション、インタラクティブキーボード、イベントサブスクリプション、ブロードキャスト
• 7 個のリソース — ボット情報、設定、チャット一覧、メッセージ履歴、イベントキュー、ファイルメタデータ、監査ログ
• 3 個のプロンプト — モデレーション、告知、ユーザー報告のためのすぐに使えるワークフロー
• 構造化出力 — すべてのツールが、プログラムで解析できる outputSchema 付きの型付き Pydantic モデルを返します
• リアルタイムイベント — ボットは MCP 通知を介して Telegram イベントを AI クライアントに送信します（ポーリング不要）
• インタラクティブメッセージ — AI エージェントがインラインキーボードメニューを作成し、ボタン操作に対応し、メッセージを編集できます
• レート制限 — 組み込みのトークンバケットにより、Telegram の 429 エラーを防ぎます
• 権限レベル — AI エージェントのアクセスを、読み取り専用、メッセージ送信、モデレーション、または管理者全権に制限できます
• 監査ログ — すべてのツール呼び出しを、タイムスタンプと引数とともに記録します
• 書き換え不要 — 既存のボットに 5 行追加するだけで、すべてのハンドラーをそのまま使えます

仕組み

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

ボットは Telegram ユーザー向けに通常どおり動作します。MCP サーバーはそのボットと並行して動作し、AI エージェントがツールとリソースを通じて同じボットを利用できるようにします。

インストール

pip install aiogram-mcp

Python 3.10+ と aiogram 3.20+ が必要です。

クイックスタート

1. ボットに aiogram-mcp を追加する

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. Claude Desktop に接続する

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "my-telegram-bot": {
      "command": "python",
      "args": ["path/to/your/bot.py"],
      "env": {
        "BOT_TOKEN": "123456:ABC-DEF..."
      }
    }
  }
}

これで Claude は、Telegram ボットでメッセージの送信、履歴の読み取り、ボタンメニューの作成、イベントへの応答を行えるようになります。

組み込みツール

メッセージング（5 個のツール）

ツール	説明
send_message	HTML/Markdown 形式のテキストを送信します
send_photo	URL を指定して写真を送信します。キャプションは任意です
forward_message	チャット間でメッセージを転送します
delete_message	メッセージを削除します
pin_message	チャット内でメッセージをピン留めします

インタラクティブメッセージ（3 個のツール）

ツール	説明
send_interactive_message	インラインキーボードボタン（コールバックまたは URL）付きのメッセージを送信します
edit_message	既存のメッセージのテキストやキーボードを編集します
answer_callback_query	ボタン操作にトーストまたはアラートで応答します

ユーザー（3 個のツール）

ツール	説明
get_bot_info	ボットのメタデータ（ユーザー名、機能）を取得します
get_chat_member_info	チャット内のユーザーの役割とプロフィールを取得します
get_user_profile_photos	ユーザーのプロフィール写真を取得します

チャット（6 個のツール）

ツール	説明
get_chat_info	チャットのメタデータ（タイトル、種類、説明）を取得します
get_chat_members_count	チャットのメンバー数を取得します
ban_user	ユーザーを永久または一時的に禁止します
unban_user	ユーザーの禁止を解除します
set_chat_title	チャットのタイトルを変更します
set_chat_description	チャットの説明を変更します

リッチメディア（10 ツール）

ツール	説明
send_document	URL を指定してファイル／ドキュメントを送信します。キャプションは任意です
send_voice	URL を指定して音声メッセージを送信します
send_video	URL を指定して動画を送信します。キャプションは任意です
send_animation	URL を指定して GIF／アニメーションを送信します
send_audio	URL、演奏者、タイトルを指定して音声／音楽を送信します
send_sticker	file_id または URL を指定してスタンプを送信します
send_video_note	URL を指定して円形のビデオメッセージを送信します
send_contact	電話番号と名前を指定して連絡先を送信します
send_location	位置情報のピンを送信します
send_poll	複数の選択肢がある投票を作成します

イベント（2 ツール）

ツール	説明
subscribe_events	チャット／種類のフィルターを指定してリアルタイムイベントを購読します
unsubscribe_events	購読を解除します

ブロードキャスト（1 ツール、オプトイン）

ツール	説明
broadcast	複数のチャットにメッセージを送信します（enable_broadcast=True が必要です）

MCP リソース

AI エージェントがツールを呼び出さずにアクセスできる読み取り専用データです。

URI	説明
telegram://bot/info	ボットのユーザー名、ID、機能
telegram://config	サーバー名と許可されたチャット ID
telegram://chats	メタデータ付きのアクティブなチャット一覧
telegram://chats/{chat_id}/history	チャット内の直近 50 件のメッセージ
telegram://events/queue	自動インクリメント ID 付きのイベントキュー
telegram://files/{file_id}	ファイルのメタデータ（サイズ、パス、一意の ID）
telegram://audit/log	ツール呼び出しの監査ログ（オプトイン）

MCP プロンプト

AI エージェントに構造化されたコンテキストを提供する、事前構築済みのワークフローです。

プロンプト	引数	機能
moderation_prompt	chat_id、user_id、reason	ユーザー情報とメッセージ履歴を取得し、警告／ミュート／BAN を提案します
announcement_prompt	topic、audience?、tone?	形式を整えた Telegram の告知文を作成します
user_report_prompt	chat_id、user_id	ユーザーの全アクティビティレポートをまとめます

リアルタイムイベントストリーミング

AI エージェントがポーリングする必要はありません。ボットがイベントを自動的にプッシュします。

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

AI エージェントは subscribe_events を一度呼び出すだけで、フィルターに一致する新しいイベントが発生するたびにプッシュ通知を受け取ります。

インタラクティブメッセージ

AI エージェントは Telegram でメニュー、確認、複数ステップのウィザードなど、完全なインタラクティブ UI を構築できます。

AI エージェントがボタン付きのメッセージを送信します。

┌─────────────────────────┐
│ Confirm deployment?     │
│                         │
│  [✅ Yes]  [❌ No]      │
│  [📖 View docs]        │
└─────────────────────────┘

ユーザーがボタンをタップ → イベントがキューに追加 → AI エージェントが応答します。

┌─────────────────────────┐
│ ✅ Deployed!            │
│                         │
│  [📋 View logs]        │
└─────────────────────────┘

ボタンの押下を捕捉するには、ボットに dp.callback_query.middleware(middleware) が必要です。

安全制御

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 が操作できるのは一覧にあるチャットのみです。デフォルト：すべてのチャット。
• enable_broadcast — 安全対策として、ブロードキャストツールはデフォルトで無効です。
• max_broadcast_recipients — 1 回のブロードキャストで対象にできるチャット数の上限です。

詳細設定

レート制限

mcp = AiogramMCP(
    bot=bot, dp=dp,
    rate_limit=30,  # requests/sec (default), 0 to disable
)

組み込みのトークンバケット型レートリミッターにより、Telegram の 429 エラーを防ぎます。すべての送信 API 呼び出しのペースは自動的に調整されます。

権限レベル

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

レベル	アクセス権
read	ボット情報、チャット情報、ユーザープロフィール
messaging	読み取りに加え、メッセージ、写真、メディア、インタラクティブメッセージの送信
moderation	メッセージングに加え、削除、ピン留め、BAN、BAN 解除、チャット設定
admin	ブロードキャストやイベント購読を含む、すべてのアクセス権

監査ログ

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

すべてのツール呼び出しが記録されます。telegram://audit/log リソースからアクセスできます。

例

例	トランスポート	機能
basic_bot.py	stdio	ミドルウェア、イベント、コールバック追跡を含む完全なセットアップ
incident_alert_bot.py	SSE	インシデント通知用のブロードキャスト対応運用ボット

開発

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

ライセンス

MIT。LICENSE を参照してください。