Skip to main content

Set up the TikTok Shop MCP server

The TikTok Shop MCP server gives AI agents access to a seller's TikTok Shop operations through the TikTok Shop Open API: shops, orders, products and inventory, fulfillment and logistics, returns and cancellations, finance, analytics, promotions, and (when TikTok grants the scope) customer service. It is read-only until an admin turns on write tools. This guide covers creating a TikTok Shop app in Partner Center, enabling scopes, and connecting the server to MintMCP with per-user OAuth.

Prerequisites​

  • A MintMCP admin account
  • A TikTok Shop seller account with an active shop for each shop you want to connect
  • A TikTok Shop Partner Center developer account for your market: partner.us.tiktokshop.com for US sellers, partner.tiktokshop.com for other markets. A seller connecting its own shops registers as a TikTok Shop seller developer; an agency or software vendor connecting shops it manages registers as an app developer and completes Partner Center's company details and registration review. TikTok's developer onboarding guide covers both paths.

An app belongs to one market, so a seller operating in several markets creates one app per market and installs one connector per app.

Create a Custom app​

  1. Sign in to Partner Center for your market and open App & Service in the navigation panel.

  2. Click Create app & service.

  3. Select Custom. Custom apps are distributed privately through an authorization link and skip the App Store listing review. TikTok still requires app review if you pick the Connector category or reach 25 seller authorizations, so choose a category that matches your operations, for example Enterprise Resource Planning. The category cannot be changed later.

  4. Enter a default name, for example MintMCP.

  5. Select the Market and Seller type (usually Local). Both are fixed after creation.

  6. Turn on Enable API.

  7. Set Redirect URL to the callback for your MintMCP region:

    MintMCP regionRedirect URL
    US (app.mintmcp.com)https://app.mintmcp.com/oauth/callback
    EU (eu.mintmcp.com)https://eu.mintmcp.com/oauth/callback

    The install drawer in MintMCP shows the callback for your organization.

  8. Leave Webhook URL empty and click Create.

TikTok's Create your App page describes each field.

Enable API scopes​

Scopes are enabled per app and granted by the seller at authorization time, so enable everything you need before anyone connects: adding a scope later means every seller has to authorize again.

  1. Open your app and go to Manage API.

  2. Enable the packages for the workflows you want to expose:

    PackageScope keyWhat it enables
    Shop Authorized Informationseller.authorization.infoList authorized shops and shop webhooks. Required.
    Global Shop Informationseller.shop.infoActive shops and seller permissions
    Order Informationseller.order.infoSearch and read orders and price details
    Product Basicseller.product.basicProducts, SKUs, inventory levels, categories, brands, listing prerequisites; activate and deactivate products
    Product Optimizationserller.product.optimize (TikTok's spelling)Product listing diagnostics
    Product Modifyseller.product.writeUpdate inventory, prices, and product details
    Fulfillment Basicseller.fulfillment.basicPackages, shipping documents, shipping services; create and ship packages
    Logistics Basicseller.logisticsWarehouses, delivery options, shipping providers, order tracking
    Return & Refund Basicseller.return_refund.basicReturns, cancellations, after-sales requests; approve or reject decisions and calculate refunds
    Finance Informationseller.finance.infoStatements, transactions, payments, withdrawals, unsettled orders
    TikTok Shop Analyticsdata.shop_analytics.public.readShop, product, SKU, video, and live performance, plus shop health
    Bestsellersdata.bestselling.public.readBestselling products, videos, and creators in your market
    Promotion Informationseller.promotion.infoPromotions and coupons
    Promotion Modifyseller.promotion.writeUpdate promotion products and deactivate promotions
    Customer Serviceseller.customer_serviceConversations, messages, and support performance; send messages and mark conversations read
    Product Reviewsprivate scopeSearch product reviews

  3. Leave global-selling, Fulfilled by TikTok, delete, and callback packages off unless you use them elsewhere.

Customer Service and Product Reviews are granted by TikTok on request rather than toggled on, so they may not appear in Manage API. Ask for them through a Partner Center support ticket with your app key and use case. The connector keeps their tools hidden until you enable them in MintMCP, so the rest of the connector works without them.

TikTok's Access scope reference lists each package.

Publish the app and copy its credentials​

  1. Publish the Custom app from its detail page. Publishing a Custom app needs no review unless one of the conditions above applies.

  2. Open App & Service > your app > App credentials (also labelled Basic information) and copy the App Key, App Secret, and Service ID. Keep the secret private.

  3. Build the seller authorization link for your market, using the Service ID (not the App Key):

    MarketSeller authorization link
    UShttps://services.us.tiktokshop.com/open/authorize?service_id=<SERVICE_ID>
    Other marketshttps://services.tiktokshop.com/open/authorize?service_id=<SERVICE_ID>

    Partner Center also shows this link on the published app's page.

Add TikTok Shop to MintMCP​

  1. In MintMCP, go to MCP store > Manage store > Recommended servers.

  2. Find TikTok Shop and click Install. The configure drawer opens with the OAuth endpoints pre-filled.

  3. Replace Authorization URL with your full seller authorization link from the previous step, including ?service_id=<SERVICE_ID>. The pre-filled value is the US host without a service ID and does not work on its own.

  4. Leave Token URL as https://auth.tiktok-shops.com/api/v2/token/get.

  5. Enter the App Key and App Secret as the OAuth client credentials.

  6. Leave Scopes empty. TikTok grants the scopes enabled on the app in Manage API, not scopes named in the link.

  7. Fill in the connector's environment variables:

    VariableValue
    TIKTOK_SHOP_APP_KEYThe same App Key. The connector signs every API request with it.
    TIKTOK_SHOP_APP_SECRETThe same App Secret. Stored encrypted.
    TIKTOK_SHOP_ENABLE_WRITESfalse. See Enable write tools.
    TIKTOK_SHOP_ENABLE_REVIEWSfalse unless TikTok granted the Product Reviews scope.
    TIKTOK_SHOP_ENABLE_CUSTOMER_SERVICEfalse unless TikTok granted the Customer Service scope.

    MintMCP uses the OAuth credentials to exchange and refresh tokens, and the connector uses the environment variables to sign API calls, so both must come from the same app.

  8. Confirm the Redirect URL shown in the drawer is the same value you set in Partner Center.

  9. Click Install.

Connect and verify​

The first time a user calls a tool, MintMCP sends them to TikTok's seller authorization page. The user signs in to Seller Center, chooses an authorization duration, and confirms. From then on MintMCP stores the tokens, refreshes the access token (TikTok issues them for 7 days), and forwards it on every call. The refresh token lasts as long as the authorization duration the user chose, so they reconnect when it lapses. The connector container never sees a refresh token.

To verify a fresh install:

  1. Call tiktok_shop_get_authorized_shops. It returns the shops the user authorized, with each shop's id and an allowed flag.
  2. Call a shop read such as tiktok_shop_search_products with one of those shop IDs.

Choose which shops the connector can reach​

Each tool call runs against one shop. The connector picks the shop from the call's shop_id argument, then from an admin-configured default, and otherwise uses the only authorized shop. When several shops are authorized and none of those apply, the tool returns the list of shops so the user can pass shop_id.

Two optional environment variables narrow this. They are not part of the install drawer because their values are shop IDs, which exist only after the first user has connected. Add them afterwards:

  1. Connect once and call tiktok_shop_get_authorized_shops to read the shop IDs.
  2. Open the connector's settings in MintMCP and add the variables under its environment settings.
  3. Save. The connector redeploys and picks up the new values.
VariableEffect
TIKTOK_SHOP_DEFAULT_SHOP_IDShop used when a call omits shop_id.
TIKTOK_SHOP_ALLOWED_SHOP_IDSComma-separated shop IDs the connector may target. Every other shop is refused, including as a default.

Remove a variable to lift the restriction. Users still authorize their own shops; the allowlist only restricts which of them the connector will use.

Enable write tools​

Write tools stay hidden from tool discovery until you enable them, and enabling them does not grant TikTok permissions: the app and the seller's grant still need the matching scope.

VariableTools it adds
TIKTOK_SHOP_ENABLE_WRITESInventory and price updates, product edits and status changes, package creation and shipping, cancellation and return decisions, refund calculation, promotion changes
TIKTOK_SHOP_ENABLE_REVIEWSProduct review search (requires the private Product Reviews scope)
TIKTOK_SHOP_ENABLE_CUSTOMER_SERVICEBuyer conversations, messages, and support performance. Sending messages and marking conversations read also require TIKTOK_SHOP_ENABLE_WRITES.

To expose only some writes, enable the category and hide individual tools with tool customization. Decision tools such as approving a return accept an idempotency_key, so an agent that retries the same decision does not apply it twice.

Security considerations​

  • The App Secret serves both the OAuth exchange and API request signing. Keep it in MintMCP only, and if you rotate it in Partner Center, update both the OAuth credentials and TIKTOK_SHOP_APP_SECRET.
  • Each user authorizes individually, so tool calls run against the shops that user authorized and are attributed to their identity in the MintMCP audit log.
  • MintMCP brokers the OAuth flow and holds the tokens. The connector receives an access token per request and stores nothing.
  • Write tools are off by default and carry MCP annotations, so clients that honor them prompt before a destructive call.
  • Leave the app's IP allow list off in Partner Center: hosted connectors do not have a fixed egress IP unless you request one.
  • A seller revokes access at any time by deauthorizing the app in Seller Center; the next call then prompts the user to reconnect.

Troubleshooting​

  • Authorization ends on a TikTok error page or never returns to MintMCP. The Redirect URL on the Partner Center app must be exactly the callback for your region (https://app.mintmcp.com/oauth/callback or https://eu.mintmcp.com/oauth/callback). Each app allows a single redirect URL, so an app already used by another system needs a second Custom app for MintMCP.
  • Authorization succeeds but calls fail with TikTok code 105005. The seller's grant lacks the scope the tool needs. Enable the package in Manage API, then have the user reconnect so the new grant includes it.
  • Calls fail with a missing or invalid token. Confirm the OAuth App Key and TIKTOK_SHOP_APP_KEY belong to the same app. A token issued for one app is rejected when signed with another app's key.
  • "No authorized shops for this account". The user authorized under a different seller account or market than the app, or TIKTOK_SHOP_ALLOWED_SHOP_IDS excludes every shop they authorized.
  • "This account is authorized for multiple shops". Pass shop_id in the call or set TIKTOK_SHOP_DEFAULT_SHOP_ID.
  • The user is asked to reconnect after weeks of use. The refresh token expired at the end of the authorization duration the user chose. Reconnecting issues a new one; pick the longest duration offered to reconnect less often.
  • A write tool is missing from the tool list. Its gate is off, or the tool was hidden through tool customization. Customer service writes need both the customer service and write gates.

Next steps​