Telegram MCP Server

MCP server sederhana untuk menghubungkan akun Telegram pribadi kamu ke AI assistant (Claude, Cursor, VS Code, Claude Code, dll).

Dibuat mirip konsep whatseal-mcp (Edo Sulai) / WhatsApp MCP style:

• Pakai user account (bukan bot) via MTProto
• Tools yang fokus & berguna
• Auth pakai session string (portable)
• Cocok untuk cari lowongan remote di channel Telegram lalu apply via email

---

Fitur (Tools)

Tool	Deskripsi
get_me	Info akun Telegram kamu
list_dialogs	List chat / grup / channel (bisa filter unread)
get_messages	Ambil pesan dari chat tertentu
send_message	Kirim pesan teks (bisa reply)
search_messages	Cari keyword (bisa filter X hari terakhir, global/per-chat) — cocok cari lowongan
mark_as_read	Tandai chat sudah dibaca
get_chat_info	Detail info chat / user / grup
download_media	Download foto/dokumen/video dari pesan
forward_message	Forward pesan ke chat lain
edit_message	Edit pesan yang sudah dikirim
delete_messages	Hapus satu atau banyak pesan
send_file	Kirim file lokal (foto, dokumen, dll)
get_contacts	List kontak Telegram

---

Setup

1. Dapatkan API ID & Hash

1. Buka https://my.telegram.org/apps
2. Login dengan nomor Telegram
3. Buat aplikasi baru (isi title & short name bebas)
4. Catat api_id dan api_hash

2. Install dependency

cd telegram-mcp
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt

3. Generate Session String

cp .env.example .env
# Edit .env → isi TELEGRAM_API_ID dan TELEGRAM_API_HASH

python generate_session.py

Ikuti prompt:

• Masukkan nomor HP (format internasional, contoh +6281234567890)
• Masukkan kode yang dikirim Telegram
• Password 2FA jika ada

Copy session string yang muncul → tempel ke .env sebagai TELEGRAM_SESSION_STRING.

Session string ini setara password. Jangan share ke siapapun.

4. Test manual

python server.py

Kalau muncul log Connected as ... berarti sukses (server menunggu input MCP via stdio).

---

Konfigurasi MCP Client

Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "telegram": {
      "command": "/ABSOLUTE/PATH/TO/telegram-mcp/.venv/bin/python",
      "args": ["/ABSOLUTE/PATH/TO/telegram-mcp/server.py"],
      "env": {
        "TELEGRAM_API_ID": "12345678",
        "TELEGRAM_API_HASH": "your_api_hash",
        "TELEGRAM_SESSION_STRING": "your_session_string"
      }
    }
  }
}

Claude Code

claude mcp add telegram -s user \\
  -e TELEGRAM_API_ID=12345678 \\
  -e TELEGRAM_API_HASH=your_hash \\
  -e TELEGRAM_SESSION_STRING=your_session \\
  -- python /path/to/telegram-mcp/server.py

---

Contoh Prompt — Use Case Cari Lowongan Remote + Apply

Workflow yang paling cocok:

1. Cari lowongan

   • "Cari pesan Telegram yang mengandung 'remote golang' dalam 7 hari terakhir"
   • "Search keyword 'backend remote' atau 'hiring remote' di semua chat"
   • "List lowongan remote di channel @nama_channel_job dalam 3 hari terakhir"

2. Listing & filter

   • "Dari hasil search tadi, list yang relevan buat backend / full-stack, ringkas masing-masing 1 paragraf"
   • "Pilih 3 lowongan yang paling cocok, kasih company + role + link apply kalau ada"

3. Apply via email (pakai Gmail yang sudah connect)

   • "Buatkan email apply untuk lowongan X"
   • "Kirim email apply ke hr@company.com dengan subject dan body yang sudah kita draft"

Prompt lain

• "Cek chat Telegram yang belum dibaca"
• "Ringkas 20 pesan terakhir dari grup XYZ"
• "Kirim pesan ke @username: ..."
• "Download media dari pesan ID ... di chat ..."

---

Catatan Keamanan

• Ini user account (MTProto). Jangan dipakai untuk spam / mass messaging → risiko ban.
• Session string = akses penuh ke akun. Simpan aman.
• Tool send_message / send_file / delete_messages bisa mengubah data atas nama kamu. Hati-hati.
• Disarankan mulai dengan tool read-only dulu, baru enable send setelah yakin.

---

Next Ideas

• Draft management
• Rate limiting
• ACL (whitelist chat tertentu)
• Transcribe voice notes
• React to messages

Kalau mau ditambah tools tertentu, bilang saja.