tiktok-shop-mcp
A Model Context Protocol server for the TikTok Shop Partner API that lets an AI assistant query orders, finance, products, and analytics across multiple configured shops (read-only; product writes are a separate opt-in set not exposed here).
Shops & auth — list configured shops with token expiry; refresh one shop's token or all shops' tokens (auto-saved to
shops.json).Orders — search orders by date range (human-friendly
YYYY-MM-DD+ IANA timezone, or raw unix timestamps), status, sort order, and page token; fetch full details for up to 50 order IDs.Finance — pull daily settlement statements and transaction details by order ID or statement ID.
Products — browse shop product listings by status, and get product detail including SKU prices.
Returns & cancellations — search refund/return orders and cancellations with refund amounts and cancel reasons, using the same date handling.
Shop analytics — GMV, orders and customers with VIDEO/LIVE/PRODUCT_CARD breakdown, hourly performance for a given day, and customer-service metrics (handling time, IM dissatisfaction) over any date window.
Performance rankings — all-products ranking by GMV/items sold/orders, single-product and single-SKU performance, and shop-wide video performance (ALL/SELF/AFFILIATE).
Creator/video GMV — auto-paginate all shop videos and aggregate GMV, orders, items sold and video count per account username.
Bestsellers — platform-wide top-100 products, creators and videos with bucketed GMV ranges (needs the Bestsellers scope) for trend and competitor scouting.
Multi-shop ergonomics — optional
seller_name(partial match, case-insensitive) on nearly every tool; structured JSON errors with asuggestionso the model can self-correct (e.g. refresh an expired token and retry).
Provides tools for querying the TikTok Shop Partner API across multiple shops, covering orders, finance, products, shop/video/SKU analytics, affiliate best-sellers, returns/cancellations, and token lifecycle management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tiktok-shop-mcp show me yesterday's orders for my US shop"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tiktok-shop-mcp
A Model Context Protocol (MCP) server for the TikTok Shop Partner API — query orders, finance, products, analytics, and affiliate performance across multiple shops from Claude, or any other MCP client.
Built for sellers and agencies who operate TikTok Shops and want their AI assistant to answer questions like "what did the US shop sell yesterday?", "which SKUs are trending this week?", or "pull the settlement statements for June" — directly against the official API, with no browser scraping.
Features
Multi-shop — configure any number of shops in one JSON file; every tool takes an optional
seller_name(partial match) to pick the shop32 tools covering orders, finance, product catalog and listing lookups, shop/video/SKU analytics, affiliate best-sellers, returns/cancellations, and gated product writes
Human-friendly dates — pass
start_date=2026-07-01+ an IANA timezone instead of unix timestamps; the server handles conversionToken lifecycle — inspect expiry and refresh access tokens (single shop or all shops) without leaving the conversation
Resilient by default — all requests go through
mcp-retry(exponential backoff + jitter on 429/5xx/network errors)Read-only by default — product write tools exist (image upload, create, partial edit, activate/deactivate), but every one of them refuses until you list the shop's exact name in
TIKTOK_SHOP_WRITE_SHOPS, and each defaults to a dry run. See Product writes. Otherwise the only thing the server writes is your ownshops.json, when it refreshes tokens, with owner-only (0600) permissions. If you never need writes, authorize the Partner Center app with read scopes only
Related MCP server: Amazon Seller MCP
Tools
Group | Tools |
Shops & auth |
|
Orders |
|
Finance |
|
Products |
|
Listing lookups |
|
Product writes (opt-in, see below) |
|
Shop analytics |
|
Video & affiliate |
|
Installation
pip install tiktok-shop-mcpOr from source, into a virtualenv, with the direct dependencies pinned to the versions the tests run against:
git clone https://github.com/Buer2333/tiktok-shop-mcp.git
cd tiktok-shop-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install --no-deps -e .requirements.txt pins the direct runtime dependencies to exact versions,
including mcp-retry, which wraps every API call and so sees your tokens.
Transitive dependencies (pydantic, starlette, and so on) are not pinned; for a
fully reproducible install, generate a lock file with pip-compile --generate-hashes. Bump a pin only after reading what changed in that release.
Compatibility
Works with both mcp 1.x and 2.x. mcp 2.0 renamed FastMCP to MCPServer
(mcp.server.mcpserver) and turned mcp.server.fastmcp into a raising stub;
server.py imports via a try-v2-except-v1 shim. Tests pass on 1.28.1 and 2.1.1;
requirements.txt pins 2.1.1.
Configuration
Credentials live in a JSON file outside the repo (default ~/.config/tiktok-mcp/shops.json, override with the TIKTOK_SHOP_CONFIG env var). The server never reads a shops.json from the project folder, so a copy there can't be picked up and synced or committed by accident. Keep the file owner-only:
chmod 700 ~/.config/tiktok-mcp && chmod 600 ~/.config/tiktok-mcp/shops.jsonThe setup scripts leave token backups (shops.json.bak.* and a recovery/ folder) next to it; delete them once your shops are working. A small shops.json.lock file also lives there; it is how the server, the cron refresher, and the setup scripts avoid writing the file at the same time, so leave it be.
[
{
"seller_name": "MY SHOP US",
"seller_base_region": "US",
"app_key": "...",
"app_secret": "...",
"access_token": "TTP_...",
"refresh_token": "TTP_...",
"shop_id": "...",
"shop_cipher": "..."
}
]You get app_key / app_secret by creating an app on the TikTok Shop Partner Center, then authorize your shop(s) to obtain tokens. shop_id / shop_cipher are returned by the authorized-shops endpoint; the bundled probe_authorized_shops.py script can fetch them for you.
The three *_bestselling tools need a shop whose app has the Bestsellers scope. The lists are platform-wide, so one such shop is enough: set TIKTOK_SHOP_BESTSELLERS_SHOP to its seller_name (partial match OK) and the tools use it whenever seller_name is omitted. Without it they fall back to the first shop in shops.json.
Adding a shop
TIKTOK_SHOP_APP_SECRET=... .venv/bin/python add_or_update_shop.py "<full_callback_url>" --seller-name "MY SHOP"TIKTOK_SHOP_APP_SECRET is only needed for the first shop on an app; after that the script reads it from the existing entry. The callback URL carries app_key and code. The code is single-use and starts with TTP_, while an app secret is 40 hex characters, so they are easy to tell apart.
To keep one business's shops apart from another's, point TIKTOK_SHOP_CONFIG at its own file for both this script and the server. Backups and the recovery/ folder follow that path.
Token lifetime
Access token: lasts about 7 days. An expired token gets
401/105002 Expired credentials; the server then refreshes it and retries once, so MCP use needs no scheduled job.Refresh token: effectively does not expire (observed expiry in 2125).
access_token_expire_in/refresh_token_expire_in: despite the names, these are Unix timestamps, not durations.*_expire_atinshops.jsonandlist_shops: real UTC dates. Entries written by older versions can show years like 2083 until their next refresh.
Claude Code
claude mcp add tiktok-shop -- tiktok-shop-mcpClaude Desktop / other MCP clients
{
"mcpServers": {
"tiktok-shop": {
"command": "tiktok-shop-mcp",
"env": { "TIKTOK_SHOP_CONFIG": "/path/to/shops.json" }
}
}
}Product writes (opt-in)
Five tools change a shop's listings. They are off unless you turn them on per shop.
Tool | Endpoint (Product API 202309) | Required params |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The gate. Every write tool checks, before it builds a request:
seller_nameis given and matches ashops.jsonentry exactly. The read tools' partial, case-insensitive match and first-shop fallback do not apply:"MY SHOP"will not select"MY SHOP US".That exact name is listed in the
TIKTOK_SHOP_WRITE_SHOPSenvironment variable (comma-separated). Unset or empty means every write tool refuses, dry runs included.
{
"mcpServers": {
"tiktok-shop": {
"command": "tiktok-shop-mcp",
"env": { "TIKTOK_SHOP_WRITE_SHOPS": "MY SHOP US" }
}
}
}Dry run first. dry_run defaults to true: the tool returns the method, path and JSON body it would send (no token, signature or app key) and makes no HTTP request. Pass dry_run=false to send. A real send then:
goes out once. Write requests skip the automatic retry used for reads, because a create that timed out may still have gone through. On a network error the result says the outcome is unknown; read the product before trying again.
reads the product back (
GET /product/202309/products/{id}) and returns it asread_back. Afterpartial_edit_productthe read-back asks for the version under review, since TikTok Shop keeps the old version live until the edit passes audit. Afteractivate_products/deactivate_productsit returns each product's status, anderrorslists per-product failures that come back with code 0.
What the tools will not do.
No full Edit Product (
PUT .../products/{id}): it overwrites every field the body leaves out.partial_edit_productrefusesskus. The API treats each top-level field as a unit, so askuslist you send stands in for the whole property; the docs do not say what happens to SKUs left out of it (they may be removed), and SKUs carry inventory. It also refuseslisting_platformsand anything not on its list (title,description,brand_id,main_images,product_attributes,package_weight,package_dimensions,video,certifications,size_chart,search_terms,key_product_features,external_product_id,save_mode,locale).No stock or price updates, product deletion, or anything touching orders, finance or promotions.
Things to know before sending.
Partial Edit leaves omitted top-level fields alone, but an object or list you do send replaces that whole property: leave out one
product_attributesentry or onepackage_dimensionsvalue and it is blanked. Send the full property.Edits other than price and inventory go back to audit. So do activations (status
PENDING). New products are audited after creation.create_productsets each SKU's openinginventory(warehouse_idfromget_warehouses,quantity). If another system syncs your stock, make the opening numbers match it; after creation, leave stock to that system.US, EU and SEA shops must use
category_versionv2; the tools default to it.The Partner Center app needs the Product Basic (
seller.product.basic) and Product Modify (seller.product.write) scopes;get_warehousesneeds Logistics Basic (seller.logistics).
Example prompts
"List my shops and when their tokens expire"
"Orders for MY SHOP US on 2026-07-18, Eastern time"
"Which creators drove the most GMV for us in the last 7 days?"
"Compare yesterday's hourly GMV curve with the day before"
"Refresh tokens for all shops"
Architecture
tiktok_shop_mcp/
├── server.py # FastMCP app — tool definitions, date handling, error envelope
├── client.py # Signed HTTP client (HMAC-SHA256 request signing, via mcp-retry)
├── config.py # Multi-shop credential loading & resolution
├── write_guard.py # Exact-name + TIKTOK_SHOP_WRITE_SHOPS gate for write tools
└── tools/ # One module per API domain (orders, finance, products, analytics…)All tools return structured JSON. Errors come back as {"error": true, "message": …, "suggestion": …} so the model can self-correct (e.g. refresh an expired token and retry).
Disclaimer
This is an independent open-source project, not affiliated with or endorsed by TikTok. Use of the TikTok Shop API is subject to TikTok's own terms.
License
Available Tools
22 toolsget_account_video_gmv_toolB
Auto-paginate all shop videos and aggregate GMV by account username. Pass usernames as comma-separated string (e.g. 'dr.elise,dr.camila') to filter specific accounts. Returns per-account totals: gmv, orders, items_sold, video count.
Inputs: currency, usernames, end_date_lt, seller_name, +2 more. Returns: result
get_creators_bestselling_toolA
Platform-wide TOP 100 bestselling creators (requires Bestsellers scope).
date: reference date YYYY-MM-DD. time_slot: "7D" (default) or "30D". author_type: "ALL" / "AFFILIATE" / "OFFICIAL". Returns bucketed gmv_range per creator. Use for BD outreach discovery.
Inputs: date, currency, time_slot, author_type, +1 more. Returns: result
get_customer_service_performance_toolA
Get shop customer-service performance (after-sales handling time, IM dissatisfaction rate, etc.) over a custom date window.
Dates are YYYY-MM-DD. support_date_ge inclusive, support_date_lt exclusive. Wraps GET /customer_service/202407/performance — replaces SPS-backend's locked 60-day window. Use seller_name to specify shop.
Inputs: seller_name, support_date_ge, support_date_lt. Returns: result
get_order_detail_toolB
Get detailed information for specific TikTok Shop orders (max 50 IDs). Use seller_name to specify which shop.
Inputs: order_ids (required), seller_name. Returns: result
get_product_detail_toolC
Get detailed product info including SKU prices. Use seller_name to specify which shop.
Inputs: product_id (required), seller_name. Returns: result
get_product_performance_toolB
Get single product performance with VIDEO/LIVE/PRODUCT_CARD breakdown. Use seller_name to specify shop.
Inputs: currency, product_id, end_date_lt, granularity, +2 more. Returns: result
get_products_bestselling_toolA
Platform-wide TOP 100 bestselling products (requires Bestsellers scope).
date: reference date YYYY-MM-DD. time_slot: "7D" (default) or "30D". category_id: optional TikTok category filter. Returns bucketed gmv_range per product — use for competitor and category-trend scouting.
Inputs: date, currency, time_slot, category_id, +1 more. Returns: result
get_shop_orders_toolB
Search TikTok Shop orders. Use seller_name to specify which shop (partial match OK, e.g. 'US' matches 'My Brand US').
Date query options (choose one):
Raw unix timestamps: create_time_ge / create_time_lt
Human-friendly dates: start_date / end_date (YYYY-MM-DD) + timezone
timezone: IANA timezone for date conversion. Use the timezone your reporting day follows, e.g. 'Etc/GMT+8' (fixed UTC-8) or 'America/New_York' (default).
When start_date is provided, it overrides create_time_ge/create_time_lt. start_date = beginning of that day in the given timezone. end_date = end of that day (if omitted, defaults to start_date = single day query).
Inputs: end_date, timezone, page_size, sort_field, +9 more. Returns: result
get_shop_performance_hourly_toolC
Get shop performance by hour for a specific date (YYYY-MM-DD). Use seller_name to specify shop.
Inputs: date, currency, seller_name. Returns: result
get_shop_performance_toolB
Get shop-level sales performance (GMV, orders, customers) with VIDEO/LIVE/PRODUCT_CARD breakdown. Dates are YYYY-MM-DD. granularity: 'ALL' (aggregate) or '1D' (daily). Use seller_name to specify shop.
Inputs: currency, end_date_lt, granularity, seller_name, +1 more. Returns: result
get_shop_products_performance_toolC
Get performance ranking for all products (GMV, orders, items_sold). Sort by gmv/items_sold/orders. Use seller_name to specify shop.
Inputs: currency, page_size, page_token, sort_field, +5 more. Returns: result
get_shop_products_toolC
Get TikTok Shop product listings. Use seller_name to specify which shop (partial match OK).
Inputs: status, page_size, seller_name, next_page_token. Returns: result
get_shop_statements_toolC
Get TikTok Shop financial statements (daily settlement records). Use seller_name to specify which shop.
Inputs: page_size, seller_name, create_time_ge, create_time_lt, +2 more. Returns: result
get_shop_transactions_toolA
Get transaction details for a specific order or statement. Provide exactly one of order_id or statement_id. Use seller_name to specify which shop.
Inputs: order_id, seller_name, statement_id. Returns: result
get_shop_videos_performance_toolB
Get performance ranking for all videos driving shop sales (GMV, views, click-through). account_type: ALL/SELF/AFFILIATE. Use seller_name to specify shop.
Inputs: currency, page_size, page_token, sort_field, +5 more. Returns: result
get_sku_performance_toolC
Get single SKU performance. Use seller_name to specify shop.
Inputs: sku_id, currency, end_date_lt, granularity, +2 more. Returns: result
get_videos_bestselling_toolA
Platform-wide TOP 100 bestselling videos (requires Bestsellers scope).
date: reference date YYYY-MM-DD. time_slot: "7D" (default) or "30D". Returns bucketed gmv_range per video — no exact GMV. Useful for trend-scouting and creator discovery.
Inputs: date, currency, time_slot, seller_name. Returns: result
list_shops_toolB
List all configured TikTok Shop accounts with their names and token expiry dates.
Inputs: random_string. Returns: result
refresh_all_tokens_toolC
Refresh access tokens for ALL configured shops. Useful for batch renewal before expiry.
Inputs: random_string. Returns: result
refresh_token_toolA
Refresh the TikTok Shop access token for a specific shop. Call when you get a 401/token expired error. New tokens are auto-saved to shops.json.
Inputs: seller_name. Returns: result
search_cancellations_toolC
Search cancelled orders with refund amounts and cancel reasons. Use start_date/end_date (YYYY-MM-DD) or raw timestamps.
Inputs: end_date, timezone, page_size, start_date, +4 more. Returns: result
search_returns_toolB
Search return/refund orders with refund amounts. Use start_date/end_date (YYYY-MM-DD) or raw timestamps.
Inputs: end_date, timezone, page_size, start_date, +4 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
The 22 tools mostly target distinct resources and actions, and clusters like the five performance tools (shop, hourly, product, SKU, videos) are differentiated by entity and granularity in their descriptions. Minor potential confusion exists between get_shop_videos_performance_tool and get_account_video_gmv_tool (both sound like shop-video GMV), but descriptions clarify the difference.
Every tool uses a uniform verb_noun pattern with a consistent '_tool' suffix (list_shops_tool, get_shop_orders_tool, search_returns_tool, refresh_token_tool). Verbs are consistently recognizable (get/list/search/refresh) and the naming is fully predictable.
22 tools sits at the heavy end, but the domain is broad (orders, products, finance, performance analytics, creator/video discovery, token management) and each tool appears to fill a distinct niche. It is well-scoped for a comprehensive TikTok Shop reporting surface rather than bloated.
Coverage spans orders, order detail, products, returns, cancellations, statements, transactions, multi-level performance, bestsellers, customer service, and token refresh — a thorough read/analytics surface. It is largely read-only, so write operations like order fulfillment, inventory, or product editing are absent, but these are minor gaps for the apparent analytics purpose.
Maintenance
Related MCP Connectors
TikTok research for AI agents. Ask ChatGPT, Claude, Cursor, Codex or any MCP client what people search, watch, say and buy on TikTok, and get real numbers back. 34 tools: weekly TikTok search volume and 7-day trends, content gaps, videos, creators, comments and caption transcripts, hashtags and sounds, TikTok Shop sales estimates for products, shops, creators, videos and LIVE streams, TikTok’s Top Ads library with CTR and retention, places, and a fair comment-giveaway picker. 17 markets. Built for marketers, agencies, TikTok Shop sellers and creators. Sign in with OAuth or an API key; 50 free credits, no card.
Connect Amazon Seller Central to Claude or ChatGPT via MCP. Orders, inventory, pricing, fees, FBA.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
TikTok Ads MCP server: run TikTok campaigns, ad groups, ads and reports from AI.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for the Shopline Open API. Exposes 140+ tools for querying and managing orders, products, customers, promotions, analytics, and store settings from your Shopline store via Claude.100MIT
- FlicenseAqualityCmaintenanceConnects Claude to your Amazon Seller Central account via the Selling Partner API, enabling queries for recent orders, sales summaries, FBA inventory, and financial events.4-
- FlicenseNot gradedqualityCmaintenanceEnables Claude to query a TikTok account on demand, retrieving profile information, recent videos, today's videos, and detailed video statistics.-
- AlicenseNot gradedqualityCmaintenanceEnables sellers to interact with Amazon Selling Partner API and Advertising API data—orders, inventory, pricing, ads, reports, and more—through MCP clients like Claude and Cursor.MIT