Skip to main content
Glama
deenesjakoruzh
Steph-ux

telegram-mcp-server

by Steph-ux
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

telegram-mcp-server

Un servidor MCP de Telegram mediante Telethon — cliente persistente, seguro contra flooding, 9 herramientas agrupadas.

Cero claves API en el código. Los archivos de sesión se almacenan localmente. Funciona con cuentas de usuario (2FA) y bots.

1. Instalación

git clone <this-repo> telegram-mcp-server
cd telegram-mcp-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

pip install -e .

Obtén tus credenciales API

  1. Ve a my.telegram.org

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

  3. Crea una aplicación → obtén tu API ID y API Hash

Autenticación única

# User account (with 2FA support)
export TG_API_ID=12345
export TG_API_HASH="your_hash_here"
telegram-mcp-server --auth --phone +33612345678

# Or via MCP tool: tg_session(action="auth", api_id=12345, api_hash="...", phone="+33612345678")

Related MCP server: telegram-mcp

2. Regístrate en tu cliente MCP

Claude Desktop / OpenCode

{
  "mcpServers": {
    "telegram": {
      "command": "telegram-mcp-server",
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Si no está en el PATH:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "telegram_mcp_server"],
      "env": {
        "TG_API_ID": "12345",
        "TG_API_HASH": "your_hash_here"
      }
    }
  }
}

Docker

docker build -t telegram-mcp .
docker run -i --rm \
  -v ~/.telegram-mcp/sessions:/root/.telegram-mcp/sessions \
  -e TG_API_ID=12345 \
  -e TG_API_HASH="your_hash" \
  telegram-mcp

3. Catálogo de herramientas (9 herramientas, 8 acciones)

tg_session — Gestión de sesión

action

Required args

Description

auth

api_id, api_hash, phone or bot_token

Autenticar (soporta 2FA)

check

—

Comprobar estado de sesión

logout

—

Eliminar sesión

tg_message — Enviar, reenviar, eliminar, responder

action

Required args

Description

send

target, text

Enviar un mensaje

forward

target, message_id, to_target

Reenviar un mensaje

delete

target, message_id

Eliminar un mensaje

reply

target, message_id, text

Responder a un mensaje

tg_chat — Operaciones de chat

action

Required args

Description

list

—

Listar chats recientes

info

target

Obtener información del chat

members

target

Listar miembros del chat

leave

target

Salir de un chat

tg_search — Búsqueda

action

Required args

Description

messages

query

Buscar mensajes (opcionalmente en target)

users

query

Buscar contactos/usuarios

channels

query

Buscar canales

tg_history — Historial de chat

action

Required args

Description

messages

target

Obtener historial de mensajes

media

target

Obtener historial solo de medios

files

target

Obtener historial solo de archivos

tg_user — Operaciones de usuario

action

Required args

Description

me

—

Obtener tu propia información

info

target

Obtener información del usuario

block

target

Bloquear un usuario

unblock

target

Desbloquear un usuario

tg_media — Enviar medios

action

Required args

Description

send_photo

target, file_path

Enviar una foto

send_video

target, file_path

Enviar un video

send_file

target, file_path

Enviar un documento

send_voice

target, file_path

Enviar una nota de voz

tg_channel — Gestión de canales

action

Required args

Description

create

title

Crear un supergrupo/canal

join

target

Unirse a un canal

leave

target

Salir de un canal

info

target

Obtener información del canal

tg_draft — Mensajes borrador

action

Required args

Description

save

target, text

Guardar un borrador

list

—

Listar borradores

delete

target

Eliminar un borrador

4. Variables de entorno

Variable

Default

Description

TG_API_ID

0

ID de API de Telegram (de my.telegram.org)

TG_API_HASH

""

Hash de API de Telegram

TG_SESSION_DIR

~/.telegram-mcp/sessions

Ubicación de los archivos de sesión

5. Seguridad

  • Límite de frecuencia: Las acciones de envío están limitadas a 5/min. Las acciones de lectura son ilimitadas.

  • Reintento automático de FloodWaitError: Espera el tiempo requerido (máximo 5 minutos).

  • Archivos de sesión: Solo locales, nunca se incluyen en git.

  • Soporte 2FA: Compatibilidad total con cuentas con autenticación de dos factores.

6. Recursos MCP

  • tg://version — Versión del servidor

  • tg://session/status — Estado de sesión

Licencia

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • tdlib-mcp-server

    Crocodile-beep
    F
    license
    Not graded
    quality
    D
    maintenance
    Connects AI agents to Telegram via the official TDLib library, enabling tools like getting user info, listing dialogs, and searching messages.
    -

  • telegram-mcp

    chenzhaoxuan0
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with Telegram Bot API for sending messages, photos, editing messages, answering callbacks, and fetching updates.
    MIT

  • telegram-mcp

    Shaan-alpha
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to interact with a user's Telegram account: list chats, read history, search, and send messages through Telegram's MTProto API.
    1
    MIT