tokopedia-client-mcp-server

Language: English | Bahasa Indonesia

A Model Context Protocol (MCP) server that gives AI assistants (Claude, GPT-4, etc.) direct access to Tokopedia — Indonesia's largest e-commerce marketplace — so they can search products, read descriptions, analyse reviews, and download review photos/videos to recommend the best products.

Disclaimer And Responsible Use

• This project is an independent, unofficial integration and is not affiliated with, endorsed by, or sponsored by Tokopedia.
• "Tokopedia" and related marks are trademarks of their respective owners.
• Users are responsible for complying with Tokopedia Terms of Service, robots/policy constraints, and applicable law in their jurisdiction.
• Do not use this project to scrape protected/private data, bypass access controls, or automate abusive traffic.
• Do not commit personal credentials, cookies, HAR captures, or other sensitive browsing artifacts to this repository.

Private Reporting Policy

• Please report security issues privately and do not open public issues for active vulnerabilities.
• Preferred channel: open a private security advisory in this repository.
• Rights-holder, abuse, or policy concerns should use the same private channel.
• Include links, impact, and reproduction details so triage can be done quickly.
• Response targets: initial acknowledgment within 72 hours and triage update within 7 days.

Features

Requirements

• Python ≥ 3.11
• Internet access to gql.tokopedia.com
• Live QR login requires the optional QR extra plus Playwright Firefox runtime: pip install .[qr] then python -m playwright install firefox

Installation

# From source
pip install .

# Optional: only needed for live QR login
pip install .[qr]

# Required after installing the QR extra
python -m playwright install firefox

# For development (includes test dependencies)
pip install -e ".[dev]"

Optional location context defaults can be provided through environment variables. By default the server sends blank location fields, so the repo does not embed any personal city, district, warehouse, or coordinate values: TOKOPEDIA_DEFAULT_USER_ADDRESS_ID, TOKOPEDIA_DEFAULT_USER_CITY_ID, TOKOPEDIA_DEFAULT_USER_DISTRICT_ID, TOKOPEDIA_DEFAULT_USER_WAREHOUSE_ID, TOKOPEDIA_DEFAULT_USER_POSTAL_CODE, TOKOPEDIA_DEFAULT_USER_LAT, and TOKOPEDIA_DEFAULT_USER_LONG.

Running the server

MCP servers communicate over stdio and are launched automatically by compatible AI clients (Claude Desktop, Cursor, etc.).

tokopedia-mcp-server

Or directly with Python:

python -m tokopedia_mcp.server

Claude Desktop integration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "tokopedia": {
      "command": "tokopedia-mcp-server"
    }
  }
}

After restarting Claude Desktop you will see the Tokopedia tools available.

Example AI prompts

• "Search for a gaming laptop under 15 million rupiah and compare the top 3."
• "Show me the reviews for product 123456 — are buyers happy with the quality?"
• "Get the shop info for 'samsung-id' — is it an official store?"
• "Fetch the review photos for product 789 so I can see what the packaging looks like."

Tool reference

search_products

get_product_detail

When variant data is available, get_product_detail may include variants.selected_confidence:

• explicit: selected options are provided directly by Tokopedia payloads.
• inferred: selected options are inferred from page title text as fallback.

When Tokopedia exposes per-variant SKU rows, get_product_detail may also include:

• variant_offers: list of variant combinations with option_name, price, price_value, stock, and variant URL.
• selected_offer: best-matched offer for currently selected variants.
• price_range: min/max price across available variant offers.

get_product_reviews

Returned review items include variant_name when Tokopedia provides variant info (for example, color/size combinations).

get_shop_info

get_review_media

download_media

generate_login_qr

Returns a transport-neutral QR payload for MCP hosts:

• Rich clients should prefer qr_image_data_url for direct rendering.
• Clients that want raw bytes can decode qr_image_base64 using qr_image_mime_type.
• Terminal-only clients can display qr_ascii.
• The server does not open any temporary window or browser popup.
• For live Tokopedia QR generation, the server bootstraps device cookies through a headless Firefox session before returning to the HTTP client flow.

Important fields in the response:

check_qr_login_status

Pass the uuid returned by generate_login_qr. Possible statuses include waiting, approved, rejected, and expired.

Development

# Run all tests
pytest

# Run tests with verbose output
pytest -v

OpenClaw Skill Bundle

This repository includes a ClawHub/OpenClaw skill bundle at:

• skills/tokopedia_unofficial_mcp/SKILL.md

Companion files:

• skills/tokopedia_unofficial_mcp/prompts.txt
• skills/tokopedia_unofficial_mcp/publish-notes.txt

For ClawHub web upload, select the skills/tokopedia_unofficial_mcp folder.

License

MIT