dhawalshah/tiktok-ads-mcp

A Model Context Protocol (MCP) server for the TikTok Business API. Connect Claude (or any MCP-compatible AI client) directly to your TikTok ad accounts to query campaigns, video performance, audience targeting, benchmarks, and more — all in natural language.
The server speaks the MCP authorization spec (2025-06-18), so it works as a remote connector anywhere Claude supports custom MCP servers — claude.ai (personal), Claude Desktop, and Claude Teams. Add **one URL**, click "Connect", sign in with TikTok, done. For a Teams plan, the org owner adds the URL once and each member individually authenticates on first use.
What you can do
Account & Business Center
- List authorized advertiser accounts under your TikTok identity
- Get advertiser metadata (currency, timezone, industry, status)
- List Business Centers, BC members, and BC assets
Campaigns, Ad Groups & Ads
- List standard campaigns and Smart+ (AI-optimised) campaigns
- List ad groups and individual ads with creatives and status
- Inspect video assets and creative fatigue scores
Reporting & Performance
- Custom reports with any TikTok dimensions and metrics over any date range
- Video-specific metrics (2s/6s views, completion rate, average watch time)
- Ad benchmark comparisons against industry CTR/CVR/CPM/CPC
- Async reports for large date ranges (partner-programme tools)
Audience, Pixels, Conversions
- Browse all interest categories for audience targeting
- Audience reach estimates
- List TikTok Pixel installs + conversion event stats
- List offline event sets
Account Operations
- Advertiser balance for the authorised account
---
How auth works
There are **two** modes. Pick one.
Mode A — Local STDIO (one user, no server)
Use this if you only want it on your own machine. Run the included one-shot OAuth flow (get_token.py / catch_auth.py) once, set TIKTOK_ACCESS_TOKEN in your env, and Claude Desktop launches the server as a subprocess. No Firestore, no Cloud Run, no public URL.
Mode B — Remote HTTP server (Claude Teams, claude.ai, multi-user)
The MCP server is also an OAuth 2.1 authorization server. When Claude connects:
1. Claude discovers our metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server.
2. Claude registers itself via Dynamic Client Registration (POST /oauth/register).
3. Claude redirects the user to /oauth/authorize. We delegate identification to TikTok Business OAuth.
4. After TikTok login, we issue our **own** opaque bearer token to Claude — TikTok credentials never leave the server.
5. On each /mcp request Claude sends our bearer; we map it server-side to the right user's stored TikTok credentials and call the TikTok Business APIs.
> **A note on access control.** TikTok returns whatever email the user signed up with — usually personal (gmail, hotmail, etc.) rather than work email. Domain-based restriction therefore isn't reliable. By default this MCP allows any TikTok Business user to connect; the security comes from TikTok's own permission model (each user only sees ad accounts their TikTok profile has been authorised for). For tighter control, set ALLOWED_EMAILS to a comma-separated allow-list of TikTok-account emails.
---
Prerequisites
- Python 3.10+
- A TikTok Business app with at least one advertiser authorised
- A Google Cloud project (Mode B only)
---
Step 1 — Create a TikTok Developer App
1. Go to the TikTok Business API Developer Portal and create an app.
2. Note your **App ID** and **Secret** (used as the OAuth client credentials).
3. Under **Advertiser redirect URLs**, add:
- http://localhost:8080/oauth/callback *(local dev)*
- https://YOUR-CLOUD-RUN-URL/oauth/callback *(Mode B — add after deploy)*
4. Note: TikTok shows a 10-minute propagation delay for new redirect URLs.