aiogram-mcp

Servidor MCP para bots de Telegram construidos con aiogram. 30 herramientas, 7 recursos, 3 indicaciones: mensajería, contenido multimedia enriquecido, moderación, teclados interactivos, transmisión de eventos en tiempo real, limitación de velocidad, permisos y registro de auditoría.

GitHub

Prueba este MCPPatrocinado

Documentación

aiogram-mcp

Conecta tu bot de Telegram a agentes de IA mediante el Protocolo de Contexto de Modelos.

aiogram-mcp convierte cualquier bot de aiogram en un servidor MCP. Clientes de IA como Claude Desktop pueden entonces enviar mensajes, leer el historial de chat, construir menús interactivos y reaccionar a eventos en tiempo real, todo a través de tu bot existente, sin reescribir ni un solo handler.

¿Por qué aiogram-mcp?

La mayoría de los servidores MCP de Telegram son envoltorios delgados con 3-5 herramientas. aiogram-mcp va más allá:

30 herramientas — mensajería, medios enriquecidos, moderación, teclados interactivos, suscripciones a eventos, difusión
7 recursos — información del bot, configuración, listas de chats, historial de mensajes, cola de eventos, metadatos de archivos, registro de auditoría
3 prompts — flujos de trabajo listos para moderación, anuncios e informes de usuarios
Salida estructurada — cada herramienta devuelve modelos Pydantic tipados con outputSchema para análisis programático
Eventos en tiempo real — el bot envía eventos de Telegram a los clientes de IA mediante notificaciones MCP (sin polling)
Mensajes interactivos — los agentes de IA crean menús de teclado en línea, manejan pulsaciones de botones, editan mensajes
Límite de velocidad — el token bucket integrado previene errores 429 de Telegram
Niveles de permisos — restringe a los agentes de IA a solo lectura, mensajería, moderación o acceso completo de administrador
Registro de auditoría — rastrea cada invocación de herramienta con marcas de tiempo y argumentos
Cero reescrituras — añade 5 líneas a tu bot existente, conserva todos tus handlers

Cómo 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    |
      | <-------------------------- | <--------------------------- |

El bot funciona normalmente para los usuarios de Telegram. El servidor MCP funciona junto a él, dando a los agentes de IA acceso al mismo bot mediante herramientas y recursos.

Instalación

pip install aiogram-mcp

Requiere Python 3.10+ y aiogram 3.20+.

Inicio Rápido

1. Añade aiogram-mcp a tu 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. Conecta Claude Desktop

Añade a tu claude_desktop_config.json:

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

Ahora Claude puede enviar mensajes, leer historiales, crear menús de botones y reaccionar a eventos en tu bot de Telegram.

Herramientas Integradas

Mensajería (5 herramientas)

Herramienta	Descripción
`send_message`	Envía texto con formato HTML/Markdown
`send_photo`	Envía una foto por URL con subtítulo opcional
`forward_message`	Reenvía un mensaje entre chats
`delete_message`	Elimina un mensaje
`pin_message`	Fija un mensaje en un chat

Mensajes Interactivos (3 herramientas)

Herramienta	Descripción
`send_interactive_message`	Envía un mensaje con botones de teclado en línea (callback o URL)
`edit_message`	Edita texto y/o teclado de un mensaje existente
`answer_callback_query`	Responde a una pulsación de botón con un toast o alerta

Usuarios (3 herramientas)

Herramienta	Descripción
`get_bot_info`	Obtiene metadatos del bot (nombre de usuario, capacidades)
`get_chat_member_info`	Obtiene el rol y perfil de un usuario en un chat
`get_user_profile_photos`	Obtiene las fotos de perfil de un usuario

Chats (6 herramientas)

Herramienta	Descripción
`get_chat_info`	Obtiene metadatos del chat (título, tipo, descripción)
`get_chat_members_count`	Obtiene el número de miembros en un chat
`ban_user`	Bloquea a un usuario (permanente o temporal)
`unban_user`	Desbloquea a un usuario
`set_chat_title`	Cambia el título del chat
`set_chat_description`	Cambia la descripción del chat

Medios Enriquecidos (10 herramientas)

Herramienta	Descripción
`send_document`	Envía un archivo/documento por URL con subtítulo opcional
`send_voice`	Envía un mensaje de voz por URL
`send_video`	Envía un video por URL con subtítulo opcional
`send_animation`	Envía un GIF/animación por URL
`send_audio`	Envía audio/música por URL con intérprete y título
`send_sticker`	Envía un sticker por file_id o URL
`send_video_note`	Envía una nota de video redonda por URL
`send_contact`	Envía un contacto con número de teléfono y nombre
`send_location`	Envía una ubicación geográfica
`send_poll`	Crea una encuesta con múltiples opciones

Eventos (2 herramientas)

Herramienta	Descripción
`subscribe_events`	Suscríbete a eventos en tiempo real con filtros de chat/tipo
`unsubscribe_events`	Elimina una suscripción

Difusión (1 herramienta, opcional)

Herramienta	Descripción
`broadcast`	Envía un mensaje a múltiples chats (requiere `enable_broadcast=True`)

Recursos MCP

Datos de solo lectura que los agentes de IA pueden acceder sin llamar a herramientas:

URI	Descripción
`telegram://bot/info`	Nombre de usuario, ID y capacidades del bot
`telegram://config`	Nombre del servidor e IDs de chats permitidos
`telegram://chats`	Lista de chats activos con metadatos
`telegram://chats/{chat_id}/history`	Últimos 50 mensajes en un chat
`telegram://events/queue`	Cola de eventos con IDs autoincrementales
`telegram://files/{file_id}`	Metadatos de archivos (tamaño, ruta, ID único)
`telegram://audit/log`	Registro de auditoría de invocaciones de herramientas (opcional)

Prompts MCP

Flujos de trabajo preconstruidos que dan a los agentes de IA contexto estructurado:

Prompt	Argumentos	Qué hace
`moderation_prompt`	`chat_id`, `user_id`, `reason`	Obtiene información del usuario + historial de mensajes, sugiere advertir/silenciar/bloquear
`announcement_prompt`	`topic`, `audience?`, `tone?`	Redacta un anuncio de Telegram con formato
`user_report_prompt`	`chat_id`, `user_id`	Compila un informe completo de actividad del usuario

Transmisión de Eventos en Tiempo Real

Los agentes de IA no necesitan hacer polling. El bot envía eventos automáticamente:

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

El agente de IA llama a subscribe_events una vez, y luego recibe notificaciones push cada vez que nuevos eventos coinciden con sus filtros.

Mensajes Interactivos

Los agentes de IA pueden construir interfaces interactivas completas en Telegram — menús, confirmaciones, asistentes de múltiples pasos:

El agente de IA envía un mensaje con botones:

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

El usuario toca un botón → el evento aparece en la cola → el agente de IA reacciona:

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

El bot necesita dp.callback_query.middleware(middleware) para capturar pulsaciones de botones.

Controles de Seguridad

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 — La IA solo puede interactuar con chats listados. Predeterminado: todos los chats.
enable_broadcast — La herramienta de difusión está deshabilitada por defecto como medida de seguridad.
max_broadcast_recipients — Limita el número de chats en una sola difusión.

Configuración Avanzada

Límite de Velocidad

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

El limitador de velocidad token bucket integrado previene errores 429 de Telegram. Todas las llamadas API salientes se espacian automáticamente.

Niveles de Permisos

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

Nivel	Acceso
`read`	Información del bot, información del chat, perfiles de usuario
`messaging`	Lectura + envío de mensajes, fotos, medios, mensajes interactivos
`moderation`	Mensajería + eliminar, fijar, bloquear, desbloquear, configuraciones del chat
`admin`	Acceso completo incluyendo difusión y suscripciones a eventos

Registro de Auditoría

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

Cada invocación de herramienta se registra. Acceso mediante el recurso telegram://audit/log.

Ejemplos

Ejemplo	Transporte	Características
basic_bot.py	stdio	Configuración completa con middleware, eventos y seguimiento de callbacks
incident_alert_bot.py	SSE	Bot de operaciones con difusión habilitada para notificaciones de incidentes

Desarrollo

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

Licencia

MIT. Ver LICENSE.