TAP Insights

Aplikasi penghubung akun TikTok ke Claude. Setelah tersambung, Claude bisa membaca dan menganalisis data akunmu untuk pengembangan branding dan affiliate keranjang kuning.

Tiga modul:

1. Metrik branding - statistik akun (follower, likes, jumlah video) dan metrik per video (views, like, komen, share, engagement rate). Sumber: TikTok Display API.
2. Keranjang kuning - GMV, jumlah order, estimasi komisi, produk terlaris, creator penyumbang terbesar. Sumber: TikTok Shop Affiliate API.
3. Kompetitor & tren - profil akun kompetitor + topik/hashtag yang sedang naik.

Aplikasi ini berbentuk MCP server: Claude tinggal disambungkan ke server ini, lalu bisa memanggil tool-tool di atas lewat bahasa biasa ("bandingkan engagement akun branding minggu ini", "produk apa paling laris bulan ini").

---

Penting dibaca dulu (jujur)

• Aplikasi sudah jadi dan bisa langsung dicoba dalam MODE MOCK (data contoh). Ini supaya tim bisa menguji alur kerja bareng Claude sebelum kredensial TikTok siap.
• Untuk data ASLI, ada syarat dari TikTok yang hanya bisa kamu/tim selesaikan:
  • Daftar app di TikTok Developers + review app (±3-7 hari).
  • Kredensial TikTok Shop dari Partner Center (akun MCN TAP kamu).
  • Setiap akun branding harus diotorisasi satu per satu (login OAuth). Token otomatis di-refresh, tapi proses login awal tetap manual per akun.
• Akun personal dapat akses API jauh lebih sedikit dari Business/Creator. Ubah akun branding ke Business/Creator dulu sebelum otorisasi.

---

1. Coba sekarang (mode mock, tanpa kredensial)

cd tap-insights-mcp
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env        # biarkan TIKTOK_MOCK=1
python selftest.py          # cek semua modul mengembalikan data contoh

Kalau selftest.py jalan tanpa error, server siap. Lanjut sambungkan ke Claude.

---

2. Sambungkan ke Claude (Claude Desktop)

Buka file konfigurasi Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Tambahkan (ganti /path/lengkap/... dengan path folder ini, dan pakai python dari .venv):

{
  "mcpServers": {
    "tap-insights": {
      "command": "/path/lengkap/tap-insights-mcp/.venv/bin/python",
      "args": ["/path/lengkap/tap-insights-mcp/server.py"]
    }
  }
}

Restart Claude Desktop. Sekarang Claude punya tool: status, branding_metrik_akun, branding_metrik_video, shop_ringkasan, shop_produk_terlaris, shop_creator_teratas, kompetitor_profil, tren_konten, dll.

Coba tanya Claude: "Panggil status" lalu "tampilkan metrik video akun alkahfi.official".

---

3. Aktifkan data ASLI

3a. Metrik branding (TikTok Display API)

1. Buka https://developers.tiktok.com -> buat app.

2. Aktifkan Login Kit dan Display API.

3. Tambahkan scope: user.info.basic, user.info.profile, user.info.stats, video.list.

4. Daftarkan Redirect URI persis: http://localhost:8080/callback.

5. Isi di .env: TIKTOK_CLIENT_KEY, TIKTOK_CLIENT_SECRET, lalu set TIKTOK_MOCK=0.

6. Otorisasi tiap akun (jalankan ulang untuk tiap akun, login pakai akun berbeda):

   python authorize.py
   

   Tip: pakai profil browser terpisah per akun supaya sesi login tidak tercampur.

3b. Keranjang kuning (TikTok Shop Affiliate API)

1. Masuk TikTok Shop Partner Center (https://partner.tiktokshop.com) dengan akun MCN TAP.
2. Buat app affiliate, ambil app_key, app_secret, dan access_token.
3. Isi di .env: TTS_APP_KEY, TTS_APP_SECRET, TTS_ACCESS_TOKEN, TTS_SHOP_CIPHER (jika diperlukan), dan TTS_BASE_URL sesuai region.
4. Samakan path endpoint di tiktok_shop.py (konstanta AFFILIATE_*) dengan dokumen resmi Partner Center versi/region kamu. Algoritma signing sudah siap; yang perlu dipastikan hanya nama path & parameter.

3c. Kompetitor & tren

Isi COMPETITOR_PROVIDER, COMPETITOR_API_KEY, COMPETITOR_BASE_URL di .env sesuai penyedia data yang dipakai (mis. Creator Search Insights API atau provider berlisensi), lalu sesuaikan _provider_get() di competitor.py.

Jangan scraping manual. Melanggar aturan TikTok dan berisiko akun diblokir.

---

Struktur file

tap-insights-mcp/
├── server.py          # MCP server: daftar semua tool untuk Claude
├── config.py          # baca kredensial dari .env + deteksi mode mock
├── storage.py         # simpan token tiap akun (SQLite) + refresh
├── authorize.py       # otorisasi akun branding via OAuth (jalankan per akun)
├── tiktok_display.py  # modul metrik branding (Display API)
├── tiktok_shop.py     # modul keranjang kuning (Shop Affiliate API + signing)
├── competitor.py      # modul kompetitor & tren
├── mock_data.py       # data contoh untuk mode mock
├── selftest.py        # uji cepat semua modul tanpa Claude
├── requirements.txt
├── .env.example
└── .gitignore

---

Keamanan

• Jangan commit .env dan file *.db ke Git (sudah masuk .gitignore).
• Token akun = akses ke akun TikTok. Simpan database di tempat aman, batasi siapa yang bisa akses server.
• Kalau pakai connector/MCP pihak ketiga di luar ini, ingat: memberi login TikTok ke pihak ketiga = memberi mereka akses. Pilih yang tepercaya.

---

Status modul saat dijalankan

Panggil tool status dari Claude kapan saja untuk melihat tiap modul sedang LIVE (pakai data asli) atau MOCK (data contoh).