# TikTok Shop [Health: Active]

**Category:** 🛒 E-Commerce  
**Repository:** https://github.com/Buer2333/tiktok-shop-mcp  
**GitHub Stars:** 7  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tiktok-shop

## Description
Read-only TikTok Shop Partner API: orders, finance, products and analytics across shops.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "tiktok-shop": {
    "command": "uvx",
    "args": ["tiktok-shop-mcp"],
    "env": {
      "TIKTOK_SHOP_CONFIG": "",
      "TIKTOK_SHOP_BESTSELLERS_SHOP": ""
    }
  }
}
```

**Requires environment variables:** `TIKTOK_SHOP_CONFIG`, `TIKTOK_SHOP_BESTSELLERS_SHOP` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What TikTok Shop does

The TikTok Shop MCP server exposes the TikTok Shop Partner API to MCP-compatible AI clients. It is designed for sellers and agencies managing one or more shops and provides structured JSON responses rather than browser-based automation. The implementation is read-only for shop data: tools do not edit listings, create products, or upload files.

Its 22 tools cover shop discovery and token management, orders, returns, cancellations, finance, products, shop performance, hourly performance, SKU metrics, customer service metrics, video performance, and affiliate-related best-seller data. This makes the TikTok Shop MCP server suitable for questions such as which products sold during a period, how a shop performed by hour, or which creators generated the most GMV.

## How it works

The server uses a signed HTTP client to call the official TikTok Shop Partner API. Requests use HMAC-SHA256 signing and pass through retry handling with exponential backoff and jitter for rate limits, server errors, and network failures. Responses are structured JSON; errors include a message and suggestion so an assistant can potentially correct a request or refresh an expired token.

Configure any number of shops in one JSON file. Every relevant tool accepts an optional `seller_name`; partial matching selects the intended shop. Date parameters can be supplied as calendar dates with an IANA time zone instead of Unix timestamps, and the server performs the conversion before making the request.

The three best-seller tools use platform-wide lists. They require a shop whose Partner Center app has the Bestsellers scope. `TIKTOK_SHOP_BESTSELLERS_SHOP` can identify that shop when a tool call does not provide `seller_name`; otherwise, the first configured shop is used.

## Setup and configuration

Install the package with `pip install tiktok-shop-mcp`, or clone the repository and install its pinned direct dependencies in a virtual environment. The package supports MCP 1.x and 2.x; the published requirements pin MCP 2.1.1.

Credentials are stored outside the repository, by default at `~/.config/tiktok-mcp/shops.json`. Set `TIKTOK_SHOP_CONFIG` to use another path. Each shop entry contains a seller name, base region, app credentials, access and refresh tokens, shop ID, and shop cipher. App credentials and authorization tokens come from TikTok Shop Partner Center, while the authorized-shops endpoint provides shop identifiers. The included `probe_authorized_shops.py` script can help retrieve them.

For a local MCP client, run `tiktok-shop-mcp` as the server command. Claude Code can add it with `claude mcp add tiktok-shop -- tiktok-shop-mcp`; other clients can use a standard stdio configuration and pass the configuration path as an environment variable. Restrict the configuration directory and file to the owner with `chmod 700` and `chmod 600`.

## Tools and capabilities

The TikTok Shop MCP server groups its tools as follows:

- Shops and authentication: list shops, inspect token status, refresh one token, or refresh all tokens.
- Orders: retrieve shop orders and order details, then search returns and cancellations.
- Finance: retrieve statements and transactions.
- Products: list catalog products and inspect product details.
- Analytics: query shop, hourly, product, SKU, video, and customer service performance.
- Video and affiliate data: retrieve account video GMV plus best-selling videos, creators, and products.

## Limitations and notes

Only read scopes should be authorized for defense in depth. The server writes to the shop configuration only when refreshing tokens, and it applies owner-only permissions. Setup scripts may leave timestamped backups, a recovery directory, and a lock file beside the configuration; the backups can be removed after setup, while the lock file should remain.

This project is independent and is not affiliated with or endorsed by TikTok. API use remains subject to TikTok's terms. The project is licensed under MIT.

_Full upstream README: https://allmcps.com/mcp/tiktok-shop/readme_