TikTok Ads MCP Troubleshooting Guide

When TikTok Ads MCP does not work, authentication is only one possible cause. Diagnose the connection from the outside in: client configuration, server process, tool discovery, identity and permissions, API response, network behavior, and the data request itself.

1. Identify the failing layer

Write down the client, MCP provider, account, exact request, time, and complete error text. Classify the symptom: the server never starts; tools are not discovered; tools are visible but calls are denied; one account is empty or forbidden; the request returns an API error, timeout, or rate-limit response; or the call succeeds with unexpected data.

This prevents changing credentials when the real issue is a malformed client configuration.

2. Check the server and client

Confirm that the configured command, runtime, package, arguments, working directory, and environment variables match the provider's current instructions. Reload or restart the client after changing MCP configuration. Inspect startup output for missing packages, invalid JSON, unsupported fields, or a process that exits immediately.

Do not put secrets in prompts or commit them to a repository. Redact tokens before sharing logs.

3. Check tools and permissions

If the server is online but no TikTok Ads tools appear, inspect its advertised capabilities and the client reload state. If tools appear but return access errors, verify the selected advertiser account, Business Center relationship, user or app identity, and minimum permission scope.

Authentication success does not prove that the identity can read the requested advertiser account.

4. Check the request and API response

Start with one account, a short date range, a small number of metrics, and no unnecessary breakdowns. Record the account, time zone, currency, conversion event, filters, pagination, and requested dimensions. A large query can time out or hit limits even when a small query works.

For API errors, preserve the status code, request shape, correlation ID if provided, and retry behavior. Avoid repeated blind retries when the response indicates a permission or validation error.

5. Explain empty or incorrect data

Empty results can mean no delivery, an overly narrow date range, delayed conversions, the wrong account, a time-zone boundary, a filter mismatch, or unavailable dimensions. Ask the agent to distinguish “zero” from “not returned” and repeat the query with the account and date range explicit.

If totals do not match the TikTok Ads interface, compare time zone, attribution, currency, status filters, reporting delay, and aggregation level before concluding that MCP data is wrong.

6. Create a minimal reproduction

Reduce the issue to one client, one server, one account, one short date range, one read-only tool, and one redacted error. Capture the configuration shape without secrets, client and server versions, timestamp, and whether another account or client behaves differently.

7. Recover safely

After correcting a setting, test account listing before campaign reporting, and campaign reporting before any write-capable action. Keep the first successful request read-only. Do not rotate credentials, broaden permissions, or change live campaigns merely to make an error disappear.

For setup instructions, see the beginner guide and client-specific Codex, Claude Code, and Cursor guides.