tokopedia-mcp
Disclaimer: Proyek ini dibuat untuk tujuan edukasi semata. Penulis tidakberafiliasi dengan Tokopedia dan tidak bertanggung jawab atas penyalahgunaanproyek ini. Gunakan dengan bijak.
Server MCP untuk pencarian produkTokopedia — 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 sidikjari 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 terlebihdahulu (di Arch: sudo pacman -S uv, di macOS: brew install uv, atau lewatinstaller 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 iniberkomunikasi langsung dengan GraphQL API internal yang digunakan aplikasi iOSresmi:
POST gql.tokopedia.com/graphql/SearchResult/getProductResult— pencarianPOST gql.tokopedia.com/graphql/ProductDetails/getPDPLayout— detail produkPOST 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 besertaidentitas perangkat acak yang segar (user id, Bd-Device-Id, payloadfingerprint, timestamp) dan sidik jari TLS Safari melalui impersonasicurl-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 daritokopaedi karyaHilmi Azizi. Terima kasih!
Lisensi
MIT
