Skip to main content
Glama

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}.

Related MCP server: Tokopedia MCP Server

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

Available Tools

3 tools
get_product_detailsA

Fetch full details for one Tokopedia product.

Provides price, description, variants, stock, media, and shop info.

Args: product_id: The numeric product id (from search_products). Takes precedence over url. url: A full tokopedia.com product URL, used when product_id is not provided.

Inputs: url, product_id. Returns: object

get_product_reviewsA

Fetch customer reviews for a Tokopedia product.

Returns a dict with a "reviews" list (messages, ratings, user info, seller responses, attached media) and the "count" of reviews returned.

Args: product_id: The numeric product id (from search_products). max_count: Maximum number of reviews (1-100, default 20).

Inputs: product_id (required), max_count. Returns: object

search_productsA

Search Tokopedia products by keyword.

Returns a dict with a "products" list (name, price in IDR, rating, shop, URL) and the "count" of results returned. Each product can be passed to get_product_details for full information.

Args: keyword: Search keyword, e.g. "logitech mouse" or "asus zenbook". max_result: Maximum number of results (1-100, default 20). pmin: Minimum price in IDR. pmax: Maximum price in IDR. condition: Product condition: 1 = new, 2 = used. shop_tier: Shop tier: 2 = Mall, 3 = Power Shop. rt: Minimum average rating, e.g. 4.5. latest_product: Only products listed within the last 7, 30, or 90 days. bebas_ongkir_extra: Only products with extra free-shipping benefit. is_discount: Only discounted products. is_fulfillment: Only products fulfilled by Tokopedia. is_plus: Only Tokopedia PLUS seller products. cod: Only products eligible for cash on delivery.

Inputs: keyword (required), rt, cod, pmax, +9 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct concern: search_products finds products, get_product_details retrieves full product information, and get_product_reviews fetches customer feedback. There is no ambiguity or overlap between their purposes.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case: search_products, get_product_details, get_product_reviews. The naming is clean and predictable, making it easy for an agent to infer function from the name.

    Tool Count5/5

    With exactly three tools, the server is well-scoped for its purpose of product discovery and research. Each tool earns its place in the set, and the count falls comfortably within the ideal range.

    Completeness5/5

    The toolkit covers the full product research lifecycle: search for products, get detailed information, and read reviews. The domain is focused on read-only product data, and there are no obvious dead ends or missing operations for that scope.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables large language models to directly access and analyze Amazon product information, including product details, variants, and reviews.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to search for products and manage order history on Tokopedia using the Model Context Protocol. It supports advanced filtering, sorting discovery, and authenticated session management via a dual MCP and web interface.
      1
      -
    • F
      license
      A
      quality
      C
      maintenance
      An MCP server that exposes marketplace seller operations (Shopee first) as tools Claude can call, enabling automation of product, pricing, inventory, customer service, and other seller tasks.
      32
      -
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that wraps the Universal Commerce Protocol (UCP) Discovery and Catalog capabilities, letting you search and compare products across UCP merchants directly from Claude.
      4
      MIT