tokopedia-mcp

Disclaimer: Proyek ini dibuat untuk tujuan edukasi semata. Penulis tidak berafiliasi dengan Tokopedia dan tidak bertanggung jawab atas penyalahgunaan proyek ini. Gunakan dengan bijak.

Server MCP untuk pencarian produk Tokopedia — mencakup pencarian produk, detail produk, dan ulasan pelanggan — yang dapat langsung digunakan dari klien LLM (Claude Desktop, Claude Code, Cursor, dan lainnya).

Dibangun dengan mcp 2.x (MCPServer), curl-cffi (untuk impersonasi sidik jari TLS), dan model pydantic. Seluruh harga dalam Rupiah (IDR).

Tools

Tool	Fungsi
search_products	Mencari produk berdasarkan kata kunci dengan filter opsional (rentang harga, kondisi, tipe toko, rating minimum, produk baru, gratis ongkir, diskon, COD, dan lainnya). Mengembalikan {products, count}.
get_product_details	Mengambil detail lengkap satu produk berdasarkan id atau URL: harga, deskripsi, varian, stok, media, dan toko.
get_product_reviews	Mengambil ulasan pelanggan: pesan, rating, informasi pengguna, dan balasan penjual. Mengembalikan {reviews, count}.

Instalasi

Membutuhkan Python >= 3.10. Pasang uv terlebih dahulu (di Arch: sudo pacman -S uv, di macOS: brew install uv, atau lewat installer resmi dari astral.sh), lalu:

uv sync            # membuat .venv sekaligus memasang dependensi

Tidak memakai uv? Bisa juga dengan pip biasa:

python -m venv .venv
.venv/bin/pip install -e '.[dev]'

Menjalankan

Menggunakan transport stdio (default — untuk klien MCP):

uv run tokopedia-mcp
# atau: uv run python -m tokopedia_mcp

Untuk transport jaringan:

uv run tokopedia-mcp --transport sse --port 8000
uv run tokopedia-mcp --transport streamable-http --port 8000

Contoh konfigurasi di Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "tokopedia": {
      "command": "/absolute/path/to/tokopedia-mcp/.venv/bin/tokopedia-mcp"
    }
  }
}

Pengujian

uv run pytest                 # pengujian offline memakai fixture terekam, tanpa internet
uv run pytest -m live         # pengujian end-to-end: menjalankan server dan memanggil Tokopedia langsung

Cara kerja

Tokopedia tidak menyediakan API pencarian produk publik, sehingga server ini berkomunikasi langsung dengan GraphQL API internal yang digunakan aplikasi iOS resmi:

• POST gql.tokopedia.com/graphql/SearchResult/getProductResult — pencarian
• POST gql.tokopedia.com/graphql/ProductDetails/getPDPLayout — detail produk
• POST gql.tokopedia.com/graphql/ProductReview/getProductReviewReadingList — ulasan

Lapisan edge (Akamai) menolak permintaan yang tidak menyerupai aplikasi asli. Karena itu setiap permintaan membawa header khusus aplikasi beserta identitas perangkat acak yang segar (user id, Bd-Device-Id, payload fingerprint, timestamp) dan sidik jari TLS Safari melalui impersonasi curl-cffi. Klien juga otomatis melakukan retry pada kegagalan sementara (backoff eksponensial) dan membuang duplikat hasil pencarian antar halaman.

Struktur proyek

src/tokopedia_mcp/
  queries.py     # query GraphQL dan path endpoint
  models.py      # model pydantic: Product, Shop, Review, SearchFilters
  extractors.py  # parsing murni: payload API -> model (dapat diuji offline)
  client.py      # TokopediaClient: HTTP asinkron, retry, paginasi
  server.py      # MCPServer + definisi tools
  __main__.py    # titik masuk CLI (stdio / sse / streamable-http)
tests/
  fixtures/      # respons asli yang terekam, dipakai pengujian offline

Kredit

Query GraphQL beserta format permintaannya diambil dari tokopaedi karya Hilmi Azizi. Terima kasih!

Lisensi

MIT