Telegram MCP: acceso local de solo lectura para agentes de IA

El servidor MCP local ofrece a Codex, Claude y otros clientes MCP tres herramientas:

El servidor funciona solo de lectura. No hay herramientas de envío, edición ni eliminación de mensajes. El servidor se ejecuta localmente a través de STDIO y deliberadamente no ofrece acceso de red HTTP/SSE.

Clientes compatibles

• ChatGPT/Codex Desktop;

• Codex CLI y extensión de IDE;

• Claude Code;

• Claude Desktop;

• cualquier cliente MCP local compatible con STDIO.

El servidor local no funciona directamente en chatgpt.com, claude.ai, en el teléfono ni en otro equipo: esos entornos no pueden ejecutar un proceso en tu máquina.

Related MCP server: tdl-mcp

Requisitos

• Windows 10/11, macOS o Linux;

• Git;

• Python 3.10+;

• al menos un cliente MCP compatible.

Instalación para principiantes

1. Abre la terminal

• macOS: Comando + Espacio → escribe Terminal → Intro.

• Windows: menú Inicio → escribe PowerShell → abre PowerShell.

• Linux: pulsa Ctrl + Alt + T o abre la aplicación Terminal.

2. Descarga el proyecto

macOS/Linux:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git ~/telegram-mcp
cd ~/telegram-mcp

Windows PowerShell:

git clone https://github.com/iamalexzatcepin/telegram-mcp-template.git "$env:USERPROFILE\telegram-mcp"
cd "$env:USERPROFILE\telegram-mcp"

Si GitHub indica que no se encuentra el repositorio, tu cuenta aún no tiene acceso al repositorio privado.

3. Obtén el API ID y el API Hash de Telegram

1. Abre my.telegram.org.

2. Inicia sesión con tu número de teléfono.

3. Abre API development tools.

4. Crea una aplicación, por ejemplo Local Telegram MCP.

5. Guarda api_id y api_hash.

No envíes api_hash, el código de acceso ni la contraseña en la nube a un chat con IA.

Crea un .env local.

macOS/Linux:

cp .env.example .env
nano .env

Guardar en Nano: Ctrl + O → Intro → Ctrl + X.

Windows PowerShell:

Copy-Item .env.example .env
notepad .env

Completa el archivo localmente:

TELEGRAM_API_ID=ваш_api_id
TELEGRAM_API_HASH=ваш_api_hash

4. Instala las dependencias e inicia sesión en Telegram

macOS/Linux:

bash setup.sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -File setup.ps1

El script encontrará Python 3.10+, creará .venv, instalará las dependencias y te pedirá el número de teléfono, el código de Telegram y, si está activada, la contraseña en la nube. Introdúcelos solo en tu terminal.

Conexión a un agente

En todos los ejemplos usa las rutas absolutas que imprima el script de instalación. El comando es Python dentro de .venv; el argumento es telegram_mcp_server.py.

Codex CLI y ChatGPT/Codex Desktop

macOS/Linux:

codex mcp add telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
codex mcp get telegram

Windows PowerShell:

codex mcp add telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
codex mcp get telegram

En ChatGPT/Codex Desktop también puedes abrir Settings → MCP servers → Add server, seleccionar STDIO y especificar los mismos Command y Arguments. Después de guardar, pulsa Restart. Los clientes locales de un mismo host de Codex comparten la configuración ~/.codex/config.toml.

Claude Code

macOS/Linux:

claude mcp add --transport stdio --scope user telegram -- "$HOME/telegram-mcp/.venv/bin/python" "$HOME/telegram-mcp/telegram_mcp_server.py"
claude mcp get telegram

Windows PowerShell:

claude mcp add --transport stdio --scope user telegram -- "$env:USERPROFILE\telegram-mcp\.venv\Scripts\python.exe" "$env:USERPROFILE\telegram-mcp\telegram_mcp_server.py"
claude mcp get telegram

Inicia una nueva sesión de Claude Code y escribe /mcp. El ámbito user hace que el servidor esté disponible en todos los proyectos locales de ese usuario.

Claude Desktop

Abre la configuración de Developer/MCP y añade un servidor STDIO local. Si tu versión de Claude Desktop usa configuración JSON, añade el objeto conservando el resto de servidores:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/telegram-mcp/telegram_mcp_server.py"]
    }
  }
}

Ubicaciones habituales del archivo:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json;

• Windows: %APPDATA%\Claude\claude_desktop_config.json.

Reinicia Claude Desktop por completo y abre un nuevo chat.

Otro cliente MCP STDIO

Usa una configuración equivalente:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/telegram_mcp_server.py"]
    }
  }
}

Comprobación final

Pide al agente:

Usa list_chats de Telegram con limit=10 y muestra el nombre, el tipo y el número de mensajes no leídos.

No des por terminada la instalación hasta que el agente haya devuelto realmente la lista de tus chats.

Varias cuentas

El servidor admite sesiones locales independientes default, work, personal y otras. Las instrucciones están en docs/MULTI_ACCOUNT.md.

Instrucciones para el agente de IA

Si la instalación la realiza Codex, Claude u otro agente, pídele que lea por completo docs/AGENT_SETUP.md y que la siga paso a paso. Ese archivo fija las reglas de seguridad y las bifurcaciones para distintos SO.

Seguridad y limitaciones

• .env y sessions/ están excluidos de Git;

• el archivo .session da acceso a la cuenta: no lo copies ni lo publiques;

• los archivos multimedia no se descargan, solo se devuelve el indicador has_media;

• las solicitudes a Telegram se realizan en nombre de tu cuenta y están sujetas a los límites de Telegram;

• no ejecutes dos operaciones con la misma .session a la vez;

• no expongas este servidor a internet.

Más información: SECURITY.md.

Si algo no funciona

Consulta docs/TROUBLESHOOTING.md.

Desarrollo

.venv/bin/python -m unittest discover -s tests -v

Estructura del proyecto:

Licencia

MIT: el proyecto puede usarse, modificarse y distribuirse conservando el aviso de derechos de autor y el texto de la licencia.