Skip to content

README.md

Latest commit

 

History

History
135 lines (90 loc) · 5.24 KB

README.md

File metadata and controls

135 lines (90 loc) · 5.24 KB
Raw

TikTok Shop Printing Press CLI/MCP

Safe v1 CLI and MCP server for confirmed TikTok Shop Seller APIs.

This package intentionally exposes a conservative surface based only on official TikTok Shop Partner Center docs: auth readiness, token exchange and refresh, shop discovery, read-only orders, products, inventory search, fulfillment packages, and warehouses. Inventory update is documented as confirmed but remains deferred until idempotency, retry, and operator-confirmation safety are designed.

Created by @cathrynlavery (Cathryn Lavery).

Install

The recommended path installs both the tiktok-shop-pp-cli binary and the pp-tiktok-shop agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI) in one shot:

npx -y @mvanhorn/printing-press-library install tiktok-shop

For CLI only (no skill):

npx -y @mvanhorn/printing-press-library install tiktok-shop --cli-only

For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):

npx -y @mvanhorn/printing-press-library install tiktok-shop --skill-only

To constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):

npx -y @mvanhorn/printing-press-library install tiktok-shop --agent claude-code
npx -y @mvanhorn/printing-press-library install tiktok-shop --agent claude-code --agent codex

Without Node (Go fallback)

If npx isn't available (no Node, offline), install the CLI directly via Go (requires Go 1.26.4 or newer):

go install github.com/mvanhorn/printing-press-library/library/commerce/tiktok-shop/cmd/tiktok-shop-pp-cli@latest

This installs the CLI only — no skill.

Pre-built binary

Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.

Install for Hermes

Install the CLI binary first. The installer writes binaries to a per-user managed bin directory by default: $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows.

npx -y @mvanhorn/printing-press-library install tiktok-shop --cli-only

Then install the focused Hermes skill.

From the Hermes CLI:

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-tiktok-shop --force

Inside a Hermes chat session:

/skills install mvanhorn/printing-press-library/cli-skills/pp-tiktok-shop --force

Restart the Hermes session or gateway if the newly installed skill is not visible immediately.

Install for OpenClaw

Install both the CLI binary and the focused OpenClaw skill. The installer defaults binaries to a per-user bin directory ($HOME/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows):

npx -y @mvanhorn/printing-press-library install tiktok-shop --agent openclaw

Restart the OpenClaw session or gateway if the newly installed skill is not visible immediately.

Configure

Use credentials obtained through official TikTok Shop Partner Center flows.

export TIKTOK_SHOP_APP_KEY="<from Partner Center>"
export TIKTOK_SHOP_APP_SECRET="<from Partner Center>"
export TIKTOK_SHOP_ACCESS_TOKEN="<from official token exchange>"
export TIKTOK_SHOP_REFRESH_TOKEN="<from official token exchange>"
export TIKTOK_SHOP_SHOP_CIPHER="<from shops info>"

Optional overrides:

export TIKTOK_SHOP_CONFIG="$HOME/.config/tiktok-shop-pp-cli/config.toml"
export TIKTOK_SHOP_BASE_URL="https://open-api.tiktokglobalshop.com"
export TIKTOK_SHOP_AUTH_BASE_URL="https://auth.tiktok-shops.com"

Examples

tiktok-shop-pp-cli doctor --json
tiktok-shop-pp-cli auth status --json
tiktok-shop-pp-cli shops info --dry-run --json
tiktok-shop-pp-cli orders list --limit 20 --json
tiktok-shop-pp-cli products get <product-id> --json
tiktok-shop-pp-cli inventory get <sku-id> --json
tiktok-shop-pp-cli fulfillment warehouses --json
tiktok-shop-pp-cli inventory update --json

--dry-run builds the request shape without sending it and redacts app key, app secret, access token, refresh token, shop cipher, auth code, and generated signature material from output.

Safety Boundaries

  • Orders, fulfillment data, buyer IDs, and returns/refunds data may contain PII.
  • Safe v1 does not implement inventory mutation, product mutation, returns/refunds, shipping label mutation, finance, or webhook registration.
  • Do not retry mutations. The only implemented network calls are read operations and official token exchange/refresh calls.
  • Do not add endpoints from SDK guesses, blog posts, copied Postman collections, or unofficial examples.

MCP

Register the MCP server with Claude Code:

claude mcp add tiktok-shop-pp-mcp -- tiktok-shop-pp-mcp

The MCP server exposes the same safe v1 read surface plus inventory_update_status, which explains why stock mutation is deferred.