使用说明
Tokopedia MCP
A Model Context Protocol (MCP) server that lets AI assistants discover and explore Tokopedia — Indonesia's marketplace. Search products, apply any of Tokopedia's filters, read full product detail and customer reviews, and inspect shops.
Zero config, no login. Everything is public, read-only data — there are no cookies, tokens, or accounts to set up. Install it and start searching.
Languages: Bahasa Indonesia
Full reference: Documentation · Changelog: CHANGELOG.md · Versioning & releases: docs/RELEASES.md
Features
- stdio transport — Works with Cursor, Claude Code, Claude Desktop, VS Code, and any MCP client that launches a local process.
- Public Tokopedia data — Search, filters, product detail, reviews, and shops. No authentication.
- Full dynamic filtering — Discover Tokopedia's real filter options for a query and apply any of them (category, brand, Official/Power store, rating, location, price, condition, …).
- In-memory caching — Short TTL to avoid hammering the API on repeated lookups.
- TypeScript + Zod — Validated tool inputs, clear error messages.
Tools
| Tool | Description |
|---|---|
search_products |
Keyword search with pagination, sort (orderBy), price range, and a generic filters map (see Filtering). Returns names, prices, ratings, shop info, product IDs, and URLs. |
get_filters_and_sorts |
Discover the valid filter and sort options for a query — the key=value pairs to feed into search_products. |
get_product_detail |
Product page data: name, price, condition, weight, seller, rating, review/sold counts, the full seller description (size charts included), spec rows, category breadcrumb, media gallery, and the numeric product ID. Takes a product URL or shopDomain + productKey. |
get_product_variants |
Lists a product's variation axes (color, size, storage, etc.) and every SKU combination with per-variant price, stock, COD status, and direct URLs. Same input as get_product_detail. |
get_product_rating_summary |
Rating distribution (how many 5★ … 1★), satisfaction percentage, and Tokopedia's aggregated review topics — judge a product without paging through every review. Same input as get_product_detail. |
get_product_promo |
Whether a product is in a running campaign: campaign name, discount, original vs campaign price, share of campaign stock sold, and the end date. Same input as get_product_detail. |
get_product_reviews |
Customer reviews for a product: rating, text, variant purchased, seller responses. Takes a product ID. |
get_similar_products |
Tokopedia's recommendations for a product's category — alternatives and cheaper equivalents. Same input as get_product_detail. |
browse_category |
Browse a category's product grid with no search keyword, plus its total product count and related categories. Takes a category path, identifier, or URL. |
get_category_tree |
Tokopedia's category taxonomy with IDs and browse URLs — discover categories for browse_category or the sc filter for search_products. |
get_shop_info |
Shop profile: stats, location, open status, Official/Power Merchant badges. Takes a shop domain or ID. |
get_shop_products |
Paginated catalog for a shop, with in-shop keyword search and sorting. |
All tools are public — no login required for any of them.
Filtering
search_products accepts a generic filters argument — a map of Tokopedia filter key/value pairs. To discover the valid keys for a query, call get_filters_and_sorts first:
get_filters_and_sorts("sepatu")
→ Jenis toko: Official/Mall → "shop_tier": "2"
→ Rating: 4★ and up → "rt": "4,5"
→ Lokasi: Bandung → "fcity": "165"
search_products("sepatu", filters={ "shop_tier": "2", "rt": "4,5" })
→ 4★+ shoes from Official stores only
Because filters are passed through generically, any option Tokopedia exposes for a query works — categories, brands, free shipping, COD, pre-order, condition, and more — without the tool hard-coding each one.
Prerequisites
- Node.js 18 or newer
Installation
From npm (recommended)
Package name: @bintangtimurlangit/tokopedia-mcp. The CLI on your PATH is tokopedia-mcp.
npm install -g @bintangtimurlangit/tokopedia-mcp
Or run without installing:
npx -y @bintangtimurlangit/tokopedia-mcp
From source (this repository)
git clone https://github.com/bintangtimurlangit/tokopedia-mcp.git
cd tokopedia-mcp
npm install
npm run build
The repo does not commit build/; run npm run build after cloning before wiring MCP to build/index.js, or use npm start / npm link and the tokopedia-mcp command locally.
Configuration
There is nothing to authenticate. Add the server to your MCP client and you're done:
{
"mcpServers": {
"tokopedia": {
"command": "npx",
"args": ["-y", "@bintangtimurlangit/tokopedia-mcp"]
}
}
}
Optional environment variables:
| Env key | Default | Purpose |
|---|---|---|
CACHE_TTL_MS |
30000 |
In-memory cache lifetime in milliseconds. |
CACHE_MAX_ENTRIES |
200 |
Max cached entries before oldest-first eviction. |
DEBUG |
false |
Set to true to log startup info to stderr. |
Cursor, Claude Code, Claude Desktop, and other hosts use the same mcpServers shape — see docs/CONFIGURATION.md for global-install and local node path variants and client-specific file locations.
Example prompts
Once the server is wired to your assistant:
- "Search Tokopedia for gaming laptops under Rp 15 million, sorted by best seller."
- "Find running shoes rated 4 stars and up from Official stores only."
- "Show me the details and top reviews for this product:
<url>." - "What does the shop
apple-authorized-resellersell, and how many transactions have they completed?"
Development
→ docs/DEVELOPMENT.md. Run the live health check with npm test. Lint, format, and typecheck with npm run lint, npm run format, and npm run typecheck.
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
Invalid request schema received |
A GraphQL query drifted from Tokopedia's registered schema. Run npm test and check DEBUG=true output; the query's field selection needs updating. |
| A search returns no results for a valid query | Tokopedia may be rate-limiting or has changed a filter key. Re-run get_filters_and_sorts to refresh valid keys, and retry. |
| Empty or stale results right after a change | In-memory cache — lower CACHE_TTL_MS or wait for the TTL to expire. |
command not found: tokopedia-mcp after clone |
The repo doesn't commit build/. Run npm run build, then point the client at build/index.js (or use npm link). |
| Client can't launch the server | Verify the mcpServers command/args path; see docs/CONFIGURATION.md for per-client variants. |
Contributing & security
CONTRIBUTING.md · SECURITY.md · Code of Conduct
License
Disclaimer
This is an unofficial project. It is not affiliated with, authorized, maintained, sponsored, or endorsed by Tokopedia or PT Tokopedia.
It works by calling Tokopedia's public web API, which can change without notice — a tool may break when Tokopedia updates its site (the npm test health check exists to catch exactly that). It reads only publicly available data and performs no account actions.
You are responsible for using this software in compliance with Tokopedia's Terms of Service and applicable law. Use reasonable request volumes. All product names, logos, and brands are property of their respective owners.
