mcp-email-client

MCP server yang menjembatani LLM (Claude) dengan inbox email kamu — bisa baca thread, bikin draft, reply, dan kirim email langsung dari chat. Fokus ke thread-aware write, bukan cuma baca inbox.

---

Fitur

• Baca & cari email — search_messages, get_message, get_thread
• Draft-first safety — semua write jadi draft dulu, kirim butuh confirm: true eksplisit. LLM bisa salah, ini safety net.
• Thread-aware reply — reply nempel di thread aslinya (In-Reply-To + References header), rapi di Gmail/Outlook.
• Multi-backend — Gmail API (OAuth) atau IMAP/SMTP (App Password), satu interface.
• Token local-first — refresh token disimpan di direktori user (~/.mcp-email/), bukan server pihak ketiga.

Cara kerja

Claude ──► search_messages("invoice") ──► thread: "194abc"
  ──► get_thread("194abc")        ──► isi thread kronologis
  ──► draft_reply("194abc", ...)  ──► DRAFT (belum terkirim)
  ──► send_reply(...)             ──► VERIFIKASI (confirm) → SENT

Detail arsitektur & alur: docs/FLOW.md.

Instalasi

# install via npm
npm install -g mcp-email-client
# lalu daftarkan ke MCP host:
#   command: mcp-email,  args: []

Setup

Mode A — App Password (recommended, tanpa OAuth)

1. Aktifkan 2-Step Verification: https://myaccount.google.com/security
2. Buat App Password: https://myaccount.google.com/apppasswords
3. Salin .env.example jadi .env, isi:

GMAIL_EMAIL=emailanda@gmail.com
GMAIL_APP_PASSWORD=abcd efgh ijkl mnop

Mode B — OAuth Gmail API

1. Buat Google Cloud Project + OAuth client (tipe "Desktop app"): https://console.cloud.google.com/apis/credentials
2. Set GMAIL_CLIENT_ID + GMAIL_CLIENT_SECRET (hapus GMAIL_EMAIL/GMAIL_APP_PASSWORD)
3. Login sekali:

npm install
npm run auth        # buka browser, izinkan gmail.modify
npm run auth:status # cek status

Connect ke Claude (MCP host)

Tambah ke config MCP host (.mcp.json / claude_desktop_config.json):

{
  "mcpServers": {
    "email": {
      "command": "node",
      "args": ["C:/code/mcp-email-client/dist/index.js"]
    }
  }
}

Tools (12)

Kategori	Tools
Read	search_messages, get_message, get_thread, list_drafts
Draft (aman)	draft_new, draft_reply
Send (butuh confirm)	send_email, send_draft, schedule_send*
Manipulasi	set_thread_state, download_attachment
Health	status

* schedule_send masih stub.

Status

✅ Semua milestone (M0–M4) selesai — 12 tool MCP, mode OAuth + App Password.

Struktur:

• src/gmailAuth.ts — OAuth2 + PKCE, callback loopback, token exchange & refresh
• src/imapClient.ts / src/smtpTransport.ts — backend App Password (IMAP read, SMTP send)
• src/tokenStore.ts — refresh token simpan local-first (~/.mcp-email/)
• src/cli.ts — login / status / logout
• src/index.ts — entry point MCP server

Test: npm test

Docs

File	Isi
docs/FLOW.md	Arsitektur, data flow, auth flow
docs/SCHEMA.md	Semua tool + param + tipe return
docs/PROGRESS.md	Status implementasi per milestone