# 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

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

### 3. Generate Session String

```bash
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

```bash
python server.py
```

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

---

## Konfigurasi MCP Client

### Claude Desktop / Cursor / VS Code

```json
{
  "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

```bash
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.