aiogram-mcp

aiogram-mcp

Conecte seu bot do Telegram a agentes de IA por meio do Model Context Protocol.

aiogram-mcp transforma qualquer bot aiogram em um servidor MCP. Clientes de IA como o Claude Desktop podem então enviar mensagens, ler o histórico de conversas, criar menus interativos e reagir a eventos em tempo real — tudo por meio do seu bot existente, sem reescrever nenhum handler.

Por que aiogram-mcp?

A maioria dos servidores MCP para Telegram são wrappers simples com 3-5 ferramentas. aiogram-mcp vai além:

• 30 ferramentas — mensagens, mídia rica, moderação, teclados interativos, assinaturas de eventos, transmissão
• 7 recursos — informações do bot, configuração, listas de chats, histórico de mensagens, fila de eventos, metadados de arquivos, log de auditoria
• 3 prompts — fluxos de trabalho prontos para moderação, anúncios e relatórios de usuários
• Saída estruturada — cada ferramenta retorna modelos Pydantic tipados com outputSchema para análise programática
• Eventos em tempo real — o bot envia eventos do Telegram para clientes de IA via notificações MCP (sem polling)
• Mensagens interativas — agentes de IA criam menus de teclado inline, lidam com pressionamentos de botões, editam mensagens
• Limitação de taxa — token bucket integrado evita erros 429 do Telegram
• Níveis de permissão — restrinja agentes de IA a somente leitura, mensagens, moderação ou acesso total de administrador
• Log de auditoria — rastreie cada invocação de ferramenta com timestamps e argumentos
• Zero reescrita — adicione 5 linhas ao seu bot existente, mantenha todos os seus handlers

Como Funciona

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

O bot funciona normalmente para usuários do Telegram. O servidor MCP roda ao lado dele, dando aos agentes de IA acesso ao mesmo bot por meio de ferramentas e recursos.

Instalação

pip install aiogram-mcp

Requer Python 3.10+ e aiogram 3.20+.

Início Rápido

1. Adicione aiogram-mcp ao seu 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. Conecte o Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Agora o Claude pode enviar mensagens, ler histórico, criar menus de botões e reagir a eventos no seu bot do Telegram.

Ferramentas Integradas

Mensagens (5 ferramentas)

Ferramenta	Descrição
send_message	Enviar texto com formatação HTML/Markdown
send_photo	Enviar uma foto por URL com legenda opcional
forward_message	Encaminhar uma mensagem entre chats
delete_message	Excluir uma mensagem
pin_message	Fixar uma mensagem em um chat

Mensagens Interativas (3 ferramentas)

Ferramenta	Descrição
send_interactive_message	Enviar uma mensagem com botões de teclado inline (callback ou URL)
edit_message	Editar texto e/ou teclado de uma mensagem existente
answer_callback_query	Responder a um pressionamento de botão com um toast ou alerta

Usuários (3 ferramentas)

Ferramenta	Descrição
get_bot_info	Obter metadados do bot (nome de usuário, capacidades)
get_chat_member_info	Obter o papel e o perfil de um usuário em um chat
get_user_profile_photos	Obter fotos de perfil de um usuário

Chats (6 ferramentas)

Ferramenta	Descrição
get_chat_info	Obter metadados do chat (título, tipo, descrição)
get_chat_members_count	Obter o número de membros em um chat
ban_user	Banir um usuário (permanente ou temporário)
unban_user	Desbanir um usuário
set_chat_title	Alterar o título do chat
set_chat_description	Alterar a descrição do chat

Mídia Rica (10 ferramentas)

Ferramenta	Descrição
send_document	Enviar um arquivo/documento por URL com legenda opcional
send_voice	Enviar uma mensagem de voz por URL
send_video	Enviar um vídeo por URL com legenda opcional
send_animation	Enviar um GIF/animação por URL
send_audio	Enviar áudio/música por URL com artista e título
send_sticker	Enviar um sticker por file_id ou URL
send_video_note	Enviar uma nota de vídeo redonda por URL
send_contact	Enviar um contato com número de telefone e nome
send_location	Enviar um pin de geolocalização
send_poll	Criar uma enquete com múltiplas opções

Eventos (2 ferramentas)

Ferramenta	Descrição
subscribe_events	Assinar eventos em tempo real com filtros de chat/tipo
unsubscribe_events	Remover uma assinatura

Transmissão (1 ferramenta, opt-in)

Ferramenta	Descrição
broadcast	Enviar uma mensagem para múltiplos chats (requer enable_broadcast=True)

Recursos MCP

Dados somente leitura que agentes de IA podem acessar sem chamar ferramentas:

URI	Descrição
telegram://bot/info	Nome de usuário, ID e capacidades do bot
telegram://config	Nome do servidor e IDs de chat permitidos
telegram://chats	Lista de chats ativos com metadados
telegram://chats/{chat_id}/history	Últimas 50 mensagens em um chat
telegram://events/queue	Fila de eventos com IDs autoincrementais
telegram://files/{file_id}	Metadados de arquivo (tamanho, caminho, ID único)
telegram://audit/log	Log de auditoria de invocações de ferramentas (opt-in)

Prompts MCP

Fluxos de trabalho pré-construídos que dão aos agentes de IA contexto estruturado:

Prompt	Argumentos	O que faz
moderation_prompt	chat_id, user_id, reason	Busca informações do usuário + histórico de mensagens, sugere aviso/mute/ban
announcement_prompt	topic, audience?, tone?	Redige um anúncio formatado do Telegram
user_report_prompt	chat_id, user_id	Compila um relatório completo de atividade do usuário

Streaming de Eventos em Tempo Real

Agentes de IA não precisam fazer polling. O bot envia eventos automaticamente:

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

O agente de IA chama subscribe_events uma vez e depois recebe notificações push sempre que novos eventos correspondem aos seus filtros.

Mensagens Interativas

Agentes de IA podem construir UIs interativas completas no Telegram — menus, confirmações, assistentes de múltiplas etapas:

O agente de IA envia uma mensagem com botões:

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

O usuário toca em um botão → o evento aparece na fila → o agente de IA reage:

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

O bot precisa de dp.callback_query.middleware(middleware) para capturar pressionamentos de botões.

Controles de Segurança

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 — a IA só pode interagir com chats listados. Padrão: todos os chats.
• enable_broadcast — a ferramenta de transmissão está desabilitada por padrão como medida de segurança.
• max_broadcast_recipients — limita o número de chats em uma única transmissão.

Configuração Avançada

Limitação de Taxa

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

O limitador de taxa token bucket integrado evita erros 429 do Telegram. Todas as chamadas de API de saída são automaticamente ritmadas.

Níveis de Permissão

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

Nível	Acesso
read	Informações do bot, informações do chat, perfis de usuário
messaging	Leitura + envio de mensagens, fotos, mídia, mensagens interativas
moderation	Mensagens + excluir, fixar, banir, desbanir, configurações do chat
admin	Acesso total incluindo transmissão e assinaturas de eventos

Log de Auditoria

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

Cada invocação de ferramenta é registrada. Acesso via recurso telegram://audit/log.

Exemplos

Exemplo	Transporte	Recursos
basic_bot.py	stdio	Configuração completa com middleware, eventos e rastreamento de callbacks
incident_alert_bot.py	SSE	Bot de operações habilitado para transmissão para notificações de incidentes

Desenvolvimento

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

Licença

MIT. Veja LICENSE.