Telegram MCP Server

Un servidor local Model Context Protocol que da a un agente de IA (Claude Code, Claude Desktop o cualquier cliente MCP) acceso controlado a tu propia cuenta de Telegram: listar chats, leer el historial, buscar y enviar mensajes, a través de la API MTProto de Telegram.

Construido con Python + Telethon. Se ejecuta enteramente en tu máquina; tu sesión de inicio nunca la abandona.

Por qué

La Bot API de Telegram no puede ver tus chats existentes; un bot es una identidad separada y solo recibe los mensajes que se le envían explícitamente. Para que un agente trabaje con tus conversaciones reales necesitas la API de cliente MTProto, autenticada como tu cuenta de usuario. Este proyecto lo envuelve en un servidor MCP pequeño y enfocado para que cualquier agente compatible con MCP pueda leer y actuar en tu Telegram, sin que tengas que escribir código de conexión cada vez.

Related MCP server: telegram-mcp

Cómo encaja

Un bot de Telegram es una identidad separada y solo ve los mensajes que se le envían. Para que un agente trabaje con tus conversaciones, el servidor se autentica como tu cuenta de usuario a través de MTProto, por eso la cadena de sesión es tan importante.

flowchart LR
    AGENT["<b>MCP client</b><br/>Claude Code · Claude Desktop<br/>or any MCP-capable agent"]

    subgraph LOCAL ["Your machine — nothing leaves it but Telegram traffic"]
        direction TB
        SRV["<b>server.py</b> · FastMCP stdio server<br/>connects lazily on first tool call<br/>verifies the session is authorized"]
        TOOLS["<b>6 tools</b><br/>get_me · list_chats · get_history<br/>search_messages · search_all · send_message"]
        ENV[("<b>.env</b> · git-ignored<br/>api_id · api_hash<br/><b>SESSION_STRING</b><br/><i>equivalent to being logged in as you</i>")]
        LOGIN["<b>login.py</b> · run once<br/>phone + code + 2FA → StringSession"]
        SRV --> TOOLS
        LOGIN -->|"writes"| ENV
        ENV -->|"reads"| SRV
    end

    subgraph TL ["Telethon → MTProto"]
        direction TB
        M1["iter_dialogs"]
        M2["iter_messages"]
        M3["SearchGlobalRequest"]
        M4["send_message"]
    end

    TG[("<b>Telegram</b><br/>your real account,<br/>your existing chats")]
    BOT(["Bot API<br/><i>cannot see your chats —<br/>this is why MTProto</i>"])

    AGENT <-->|"MCP over stdio"| SRV
    TOOLS --> M1
    TOOLS --> M2
    TOOLS --> M3
    TOOLS --> M4
    TL <--> TG
    BOT -.->|"✗"| TG

    classDef secret fill:#7f1d1d,stroke:#f87171,stroke-width:2px,color:#fee2e2
    classDef no fill:#0f172a,stroke:#475569,stroke-width:1.5px,color:#94a3b8
    classDef core fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#e2e8f0
    class ENV secret
    class BOT no
    class SRV,TOOLS core

Los resultados vuelven como diccionarios planos serializables en JSON, por lo que el agente resume a partir de datos estructurados en lugar de texto extraído.

Características

• 6 herramientas que cubren las acciones comunes de lectura/escritura (ver abajo)

• Solo local — las credenciales y la sesión viven en un .env ignorado por git; nada se envía a ningún sitio excepto a Telegram

• Servidor MCP stdio estándar — funciona con Claude Code, Claude Desktop o cualquier cliente MCP

• Inicio de sesión único — el script interactivo guarda una cadena de sesión reutilizable; sin reautenticación en cada ejecución

• Pequeño y legible — ~150 líneas de Python, fácil de auditar y ampliar

Herramientas

chat acepta un nombre de usuario (@name), id numérico, número de teléfono, enlace t.me o el nombre para mostrar del chat.

Inicio rápido

1. Instalación

git clone https://github.com/<you>/telegram-mcp.git
cd telegram-mcp
python -m venv .venv

# Windows
.venv\Scripts\pip install -r requirements.txt
# macOS / Linux
.venv/bin/pip install -r requirements.txt

2. Obtén las credenciales de API

Ve a my.telegram.org → API development tools → crea una aplicación → copia el api_id y api_hash.

3. Inicia sesión (una vez)

# Windows
.venv\Scripts\python login.py
# macOS / Linux
.venv/bin/python login.py

Introduce tu api_id/api_hash, número de teléfono (con código de país) y el código de inicio de sesión que Telegram te envía (además de tu contraseña 2FA si está configurada). Esto escribe una sesión reutilizable en .env.

4. Regístralo en tu cliente MCP

Claude Code:

claude mcp add telegram --scope user -- "/abs/path/.venv/bin/python" "/abs/path/server.py"

Claude Desktop; añádelo a claude_desktop_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "/abs/path/.venv/bin/python",
      "args": ["/abs/path/server.py"]
    }
  }
}

Reinicia tu cliente y las herramientas telegram estarán disponibles.

Ejemplo

Tú: Busca en todos mis chats de Telegram "invoice" y resume lo que está pendiente.

El agente llama a search_all("invoice"), que devuelve:

[
  {
    "id": 84213,
    "date": "2026-07-02T09:14:00+00:00",
    "chat": "Acme Billing",
    "from": "Acme Billing",
    "text": "Invoice #204 is due on the 10th."
  }
]

…y el agente resume a partir de ahí.

Cómo funciona

login.py autentica una vez mediante Telethon y guarda una StringSession en .env. server.py construye un servidor stdio FastMCP, se conecta de forma diferida en la primera llamada a una herramienta, verifica que la sesión esté autorizada y asigna cada herramienta a una llamada de Telethon (iter_dialogs, iter_messages, SearchGlobalRequest, send_message). Los resultados se devuelven como diccionarios planos serializables en JSON.

Seguridad

• Mantén .env privado. La SESSION_STRING equivale a estar autenticado como tú. Está ignorada por git; nunca la hagas commit.

• Todo se ejecuta localmente; el servidor solo habla con los servidores de Telegram.

• Automatizar una cuenta de usuario es un área gris en los ToS de Telegram. Leer tu propia cuenta normalmente no es problema; mantén un ritmo de envío humano y evita la actividad masiva o de spam para mantenerte dentro de los límites de la cuenta.

Limitaciones

• Aún no hay suite de pruebas automatizada; verificado manualmente con una cuenta real.

• search_messages busca en un solo chat; usa search_all para una búsqueda global.

• La resolución del nombre para mostrar recurre a escanear tu lista de diálogos, por lo que los nombres de usuario/ids exactos son más rápidos y fiables.

Licencia

MIT