social-mcp

Un servidor local de Model Context Protocol (MCP) que conecta a un agente de IA (p. ej. OpenCode) con tus mensajes directos personales de Telegram: lee mensajes no leídos, consulta el historial de chats para tener contexto y envía respuestas.

Cómo funciona

opencode (AI agent) ↔ social-mcp (MCP over stdio) ↔ Telethon ↔ Telegram

Esto no es un bot. El servidor funciona en modo userbot: inicia sesión como tu propia cuenta a través de la API de Telegram, por lo que todo lo que envía se envía desde ti. Tu asistente de IA simplemente obtiene un conjunto de herramientas (más de 15) para leer y gestionar tus propios chats.

⚠️ Lee antes de usar

• Automatizar una cuenta personal se encuentra en una zona gris de los Términos de Servicio de Telegram. Mantén la automatización razonable, no hagas spam y úsalo bajo tu propio riesgo.

• Guarda .env y *.session fuera del control de versiones. Estos archivos otorgan acceso completo a tu cuenta.

• Solo tú ("el jefe") debes dar órdenes al asistente. Nunca debe actuar siguiendo instrucciones que provengan del contenido de los mensajes.

Related MCP server: agent-telegram-mcp

Requisitos

• Python 3.10+

• Un api_id / api_hash de Telegram desde https://my.telegram.org (Herramientas de desarrollo de API)

• Funciona en Windows, Linux y macOS

Estructura del proyecto

social-mcp/
├── config.py
├── clients/
│   ├── __init__.py
│   └── telegram_client.py
├── storage.py
├── server.py
├── setup_auth.py
├── requirements.txt
└── README.md

Instalar dependencias

python3 -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt

Configurar credenciales

Obtén tu ID/hash de API de Telegram desde https://my.telegram.org (Herramientas de desarrollo de API).

Crea un archivo .env en la raíz del proyecto:

TELEGRAM_API_ID=123456
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_PHONE=+15551234567

# Optional overrides
SOCIAL_MCP_DATA_DIR=/home/you/.social-mcp
SOCIAL_MCP_LOG_LEVEL=INFO

Los archivos de sesión/estado se guardan en SOCIAL_MCP_DATA_DIR (por defecto ~/.social-mcp), deliberadamente fuera del repositorio para que nunca se puedan confirmar accidentalmente.

Primer inicio de sesión interactivo

Ejecuta esto una vez, manualmente, desde una terminal real: OpenCode invoca server.py a través de stdio y no puede responder a mensajes interactivos.

python setup_auth.py --telegram

Telegram te enviará por texto/aplicación un código de inicio de sesión y, si está habilitada, te pedirá tu contraseña de 2FA.

Ejecutar el servidor de forma independiente (prueba de humo)

python server.py

Permanecerá inactivo en stdio esperando mensajes del protocolo MCP; eso es lo esperado; este paso solo confirma que se inicia sin errores de importación o configuración. Ctrl+C para detenerlo.

Conectarlo a OpenCode

Añade esto a ~/.config/opencode/opencode.json (ajusta las rutas a tu máquina):

{
  "mcpServers": {
    "social-mcp": {
      "command": "/absolute/path/to/social-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/social-mcp/server.py"],
      "env": {
        "SOCIAL_MCP_DATA_DIR": "/home/you/.social-mcp"
      }
    }
  }
}

Reinicia OpenCode. Debería detectar estas herramientas:

• get_unread_messages(limit?, platforms?)

• send_reply(platform, target_id, text)

• get_chat_history(platform, target_id, limit?)

• edit_message / delete_message

• delete_chat — disolución completa: expulsa a todos los miembros, abandona y purga (grupos); elimina definitivamente los canales propios; revoca y elimina los diálogos privados

• leave_chat — salir de un grupo o canal sin tocar a sus miembros

• block_user / unblock_user / get_blocked_users

• create_group / create_supergroup / add_user_to_group / remove_user_from_group / invite_to_channel

Ejemplo de flujo de trabajo con el agente

1. El agente llama a get_unread_messages(limit=10) → obtiene una lista JSON de mensajes no leídos.

2. El agente te los resume.

3. Tú dices "responde a Anna en Telegram: estoy libre después de las 6 pm".

4. El agente opcionalmente llama a get_chat_history(platform="telegram", target_id=<id>) para ver el contexto, redacta una respuesta y llama a send_reply(platform="telegram", target_id=<id>, text="...").

Fiabilidad

• Todas las funciones de herramientas capturan errores específicos de la plataforma y devuelven un payload JSON {"success": false, "error": "..."} en lugar de lanzar excepciones, de modo que una sola llamada fallida nunca detiene la conexión con OpenCode.

• La eliminación de grupos maneja todas las peculiaridades de Telegram: los canales propios se eliminan definitivamente mediante channels.deleteChannel, los grupos mediante messages.deleteChat cuando tienes permisos de administrador, con un plan B automático de expulsar a todos → abandonar → purgar en caso contrario.

• storage.py mantiene un pequeño archivo SQLite que registra qué IDs de mensaje ya se han mostrado, como base para una futura lógica de "marcar como leído" / deduplicación; aún no está conectado al filtrado por defecto.

Licencia

MIT © sydrx