@channel47/tiktok-ads-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 channel47
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# @channel47/tiktok-ads-mcp
+
+MCP server for TikTok Ads using the TikTok for Business API (`v1.3`).
+
+This server exposes four tools expected by channel47 TikTok workflows:
+
+- `list_accounts`
+- `query`
+- `report`
+- `mutate`
+
+## Installation
+
+### Standalone
+
+```bash
+npx @channel47/tiktok-ads-mcp@latest
+```
+
+### Claude Code
+
+```bash
+claude mcp add tiktok-ads --env TIKTOK_ADS_ACCESS_TOKEN=<token> -- npx @channel47/tiktok-ads-mcp@latest
+```
+
+Or as JSON config:
+
+```json
+{
+  "mcpServers": {
+    "tiktok-ads": {
+      "command": "npx",
+      "args": ["@channel47/tiktok-ads-mcp@latest"],
+      "env": {
+        "TIKTOK_ADS_ACCESS_TOKEN": "<token>",
+        "TIKTOK_ADS_ADVERTISER_ID": "<advertiser id>"
+      }
+    }
+  }
+}
+```
+
+### Monorepo Development
+
+```bash
+cd mcps
+npm install
+npm run test
+```
+
+## Getting Credentials
+
+1. Create a developer app at [TikTok for Business Developers](https://business-api.tiktok.com/portal) (Marketing API).
+2. Authorize the app against your advertiser account(s) via the app's authorization URL.
+3. Exchange the returned `auth_code` for a long-lived access token at `POST /open_api/v1.3/oauth2/access_token/`.
+4. Use that token as `TIKTOK_ADS_ACCESS_TOKEN`. The token is sent as the `Access-Token` request header (not `Authorization: Bearer`).
+
+## Configuration
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `TIKTOK_ADS_ACCESS_TOKEN` | TikTok Business API long-lived access token |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `TIKTOK_ADS_ADVERTISER_ID` | Default advertiser ID used when `advertiser_id` is omitted |
+| `TIKTOK_ADS_APP_ID` | Developer app ID — only needed so `list_accounts` can discover authorized advertisers via `/oauth2/advertiser/get/` |
+| `TIKTOK_ADS_APP_SECRET` | Developer app secret (pairs with `TIKTOK_ADS_APP_ID`) |
+| `TIKTOK_ADS_READ_ONLY` | Set to `true` to disable live mutations |
+| `TIKTOK_ADS_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds (default `30000`) |
+
+## Tool Reference
+
+### `list_accounts`
+
+List accessible TikTok ad accounts (advertisers).
+
+**Params:**
+- `advertiser_ids` (optional): explicit advertiser ids to look up
+
+**Notes:**
+- With `TIKTOK_ADS_APP_ID` + `TIKTOK_ADS_APP_SECRET` set, ids are discovered via `GET /oauth2/advertiser/get/`
+- Without app credentials, pass `advertiser_ids` or set `TIKTOK_ADS_ADVERTISER_ID`
+- Details (name, status, currency, timezone, company, country) come from `GET /advertiser/info/` (batched 100 ids per request)
+
+### `query`
+
+Structured query wrapper for TikTok Business API entities:
+
+- `campaigns` — `GET /campaign/get/`
+- `adgroups` — `GET /adgroup/get/`
+- `ads` — `GET /ad/get/`
+
+**Params:**
+- `entity` (required)
+- `advertiser_id` (optional if `TIKTOK_ADS_ADVERTISER_ID` exists)
+- `fields`: array or comma-separated string (entity-specific defaults)
+- `filtering`: TikTok filtering object, e.g. `{ "campaign_ids": ["123"], "primary_status": "STATUS_DELIVERY_OK" }`
+- `limit`: max rows (default `100`, max `1000`); pagination via `page`/`page_size` is handled automatically
+
+### `report`
+
+Synchronous integrated reporting via `GET /report/integrated/get/`.
+
+**Params:**
+- `advertiser_id` (optional if `TIKTOK_ADS_ADVERTISER_ID` exists)
+- `report_type`: `BASIC` (default) or `AUDIENCE`
+- `data_level`: `AUCTION_ADVERTISER`, `AUCTION_CAMPAIGN` (default), `AUCTION_ADGROUP`, `AUCTION_AD`
+- `dimensions`: defaults to the data_level id dimension plus `stat_time_day`
+- `metrics`: defaults to `spend, impressions, clicks, ctr, cpc, cpm, conversion, cost_per_conversion, conversion_rate`
+- `start_date` / `end_date` (`YYYY-MM-DD`, default trailing 7 days UTC) or `lifetime: true`
+- `filtering`: array of `{ field_name, filter_type, filter_value }` clauses
+- `order_field` / `order_type` (`ASC` / `DESC`)
+- `limit`: max rows (default `100`, max `1000`)
+
+Rows are returned with `dimensions` and `metrics` flattened into a single object per row.
+
+### `mutate`
+
+Mutation tool with dry-run safety by default.
+
+**Operation format:**
+
+```json
+{
+  "entity": "campaign",
+  "action": "update",
+  "id": "1781234567890",
+  "params": {
+    "budget": 500
+  }
+}
+```
+
+**Supported entities:** `campaign`, `adgroup`, `ad`
+
+**Supported actions:**
+- `create` — `POST /<entity>/create/`; campaign and adgroup creates default `operation_status` to `DISABLE` (paused) — pass explicit `operation_status` to override
+- `update` — `POST /<entity>/update/`; `id` maps to `campaign_id`/`adgroup_id`. Ad updates take the full `/ad/update/` body in `params` (ads are identified via `creatives[].ad_id`), so `id` is optional
+- `pause` / `enable` / `delete` — `POST /<entity>/status/update/` with `operation_status` `DISABLE` / `ENABLE` / `DELETE`
+
+**Top-level params:**
+- `operations` (required)
+- `advertiser_id` (optional if `TIKTOK_ADS_ADVERTISER_ID` exists)
+- `dry_run` (default `true`)
+- `partial_failure` (default `true`)
+
+**Safety notes:**
+- TikTok has **no server-side validate-only mode**. `dry_run: true` validates operations locally and returns a preview of the exact requests (method, path, body) without calling the API.
+- `delete` is permanent and unrecoverable — prefer `pause`.
+- Set `TIKTOK_ADS_READ_ONLY=true` to remove the mutate tool entirely.
+
+## Behavior Notes
+
+- Auth is sent via the `Access-Token` request header
+- TikTok returns HTTP `200` with an envelope `{ code, message, request_id, data }`; any non-zero `code` is surfaced as an error including the API code and message
+- Complex GET params (`fields`, `filtering`, `dimensions`, `metrics`, `advertiser_ids`) are JSON-encoded into the query string automatically
+- API retries once on HTTP `429` or envelope error code `40100` (rate limit), honoring `Retry-After` when present (fallback `60s`)
+- Requests are aborted on timeout (default `30000ms`, configurable via `TIKTOK_ADS_REQUEST_TIMEOUT_MS`)
+- List endpoints paginate with `page`/`page_size` (`data.page_info.total_page`)
+
+## Development Commands
+
+```bash
+cd tiktok-ads
+npm test
+node server/index.js
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@channel47/tiktok-ads-mcp",
+  "version": "0.1.0",
+  "description": "TikTok Ads MCP Server - Query and mutate TikTok for Business ads data via the Business API",
+  "main": "server/index.js",
+  "bin": {
+    "tiktok-ads-mcp": "server/index.js"
+  },
+  "type": "module",
+  "files": [
+    "server/**/*.js",
+    "server/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test *.test.js test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tiktok-ads",
+    "tiktok-for-business",
+    "analytics",
+    "advertising",
+    "claude"
+  ],
+  "author": "channel47",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/channel47/mcps.git",
+    "directory": "tiktok-ads"
+  },
+  "bugs": {
+    "url": "https://github.com/channel47/mcps/issues"
+  },
+  "homepage": "https://github.com/channel47/mcps/tree/main/tiktok-ads#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/server/auth.js

@@ -0,0 +1,59 @@
+const REQUIRED_ENV_VARS = ['TIKTOK_ADS_ACCESS_TOKEN'];
+
+let cachedAccessToken = null;
+
+/**
+ * Validate required environment variables for TikTok Ads auth.
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+export function validateEnvironment() {
+  const missing = REQUIRED_ENV_VARS.filter((name) => !process.env[name]);
+  return {
+    valid: missing.length === 0,
+    missing
+  };
+}
+
+/**
+ * Return the configured TikTok Ads access token with process-level caching.
+ * @returns {Promise<string>}
+ */
+export async function getAccessToken() {
+  if (cachedAccessToken) {
+    return cachedAccessToken;
+  }
+
+  const { valid, missing } = validateEnvironment();
+  if (!valid) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+
+  cachedAccessToken = String(process.env.TIKTOK_ADS_ACCESS_TOKEN);
+  return cachedAccessToken;
+}
+
+/**
+ * Return optional developer app credentials used for advertiser discovery
+ * via GET /oauth2/advertiser/get/, or null when not configured.
+ * @returns {{ appId: string, appSecret: string } | null}
+ */
+export function getAppCredentials() {
+  const appId = process.env.TIKTOK_ADS_APP_ID;
+  const appSecret = process.env.TIKTOK_ADS_APP_SECRET;
+
+  if (!appId || !appSecret) {
+    return null;
+  }
+
+  return {
+    appId: String(appId),
+    appSecret: String(appSecret)
+  };
+}
+
+/**
+ * Clear the in-memory token cache (used by tests and local dev flows).
+ */
+export function clearAuthCache() {
+  cachedAccessToken = null;
+}

package/server/http.js

@@ -0,0 +1,201 @@
+import { getAccessToken } from './auth.js';
+import { invalidParamsError } from './utils/errors.js';
+
+/**
+ * Base URL for all TikTok for Business API requests used by this server.
+ */
+export const TIKTOK_BASE_URL = 'https://business-api.tiktok.com/open_api/v1.3';
+const RATE_LIMIT_ERROR_CODES = new Set([40100]);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RATE_LIMIT_SLEEP_MS = 60_000;
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function normalizePath(path) {
+  if (!path) {
+    throw new Error('API path is required');
+  }
+
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+// TikTok GET endpoints expect complex params (arrays/objects such as
+// filtering, fields, dimensions, metrics) as JSON-encoded strings.
+function serializeParamValue(value) {
+  if (Array.isArray(value) || (value && typeof value === 'object')) {
+    return JSON.stringify(value);
+  }
+
+  return String(value);
+}
+
+function buildUrl(path, params = {}) {
+  const url = new URL(`${TIKTOK_BASE_URL}${normalizePath(path)}`);
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    url.searchParams.set(key, serializeParamValue(value));
+  }
+
+  return url;
+}
+
+async function parseResponse(response) {
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function extractEnvelopeCode(payload) {
+  const code = Number(payload?.code);
+  return Number.isFinite(code) ? code : 0;
+}
+
+function extractErrorMessage(payload) {
+  if (payload?.message) {
+    return payload.message;
+  }
+
+  if (typeof payload === 'string' && payload) {
+    return payload;
+  }
+
+  return 'Unknown TikTok Ads API error';
+}
+
+function resolveTimeoutMs(timeoutMs) {
+  const candidate = timeoutMs ?? process.env.TIKTOK_ADS_REQUEST_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS;
+  const parsed = Number(candidate);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return Math.floor(parsed);
+}
+
+function getRateLimitSleepMs(response) {
+  const retryAfter = response?.headers?.get('retry-after');
+  if (!retryAfter) {
+    return DEFAULT_RATE_LIMIT_SLEEP_MS;
+  }
+
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds > 0) {
+    return Math.floor(seconds * 1000);
+  }
+
+  const retryAtMs = Date.parse(retryAfter);
+  if (Number.isFinite(retryAtMs)) {
+    const delta = retryAtMs - Date.now();
+    if (delta > 0) {
+      return Math.floor(delta);
+    }
+  }
+
+  return DEFAULT_RATE_LIMIT_SLEEP_MS;
+}
+
+/**
+ * Execute an authenticated TikTok for Business API request with timeout and retry handling.
+ *
+ * TikTok returns HTTP 200 with an envelope `{ code, message, request_id, data }`;
+ * any non-zero `code` is treated as an error. The full envelope is returned on
+ * success so callers can read `data.list` and `data.page_info`.
+ * @param {string} path
+ * @param {Record<string, unknown>} [params]
+ * @param {{
+ *   method?: string,
+ *   body?: unknown,
+ *   timeoutMs?: number,
+ *   retryThrottled?: boolean,
+ *   sleep?: (ms: number) => Promise<void>
+ * }} [options]
+ * @returns {Promise<unknown>}
+ */
+export async function tiktokRequest(
+  path,
+  params = {},
+  {
+    method = 'GET',
+    body,
+    timeoutMs,
+    retryThrottled = true,
+    sleep: sleepFn = sleep
+  } = {}
+) {
+  const token = await getAccessToken();
+  const url = buildUrl(path, params);
+  const resolvedTimeoutMs = resolveTimeoutMs(timeoutMs);
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, resolvedTimeoutMs);
+
+  const requestOptions = {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      'Access-Token': token
+    },
+    signal: controller.signal
+  };
+
+  if (body !== undefined && body !== null) {
+    requestOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+
+  let response;
+  try {
+    response = await fetch(url, requestOptions);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`TikTok Ads API request timed out after ${resolvedTimeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  const payload = await parseResponse(response);
+  const envelopeCode = extractEnvelopeCode(payload);
+
+  if (response.ok && envelopeCode === 0) {
+    return payload;
+  }
+
+  if (response.status === 401) {
+    const message = extractErrorMessage(payload);
+    throw invalidParamsError(`TikTok Ads API request failed (${response.status}): ${message}`);
+  }
+
+  const isRateLimited = response.status === 429 || RATE_LIMIT_ERROR_CODES.has(envelopeCode);
+  if (isRateLimited && retryThrottled) {
+    await sleepFn(getRateLimitSleepMs(response));
+
+    return tiktokRequest(path, params, {
+      method,
+      body,
+      timeoutMs: resolvedTimeoutMs,
+      retryThrottled: false,
+      sleep: sleepFn
+    });
+  }
+
+  const message = extractErrorMessage(payload);
+  const codeSuffix = envelopeCode !== 0 ? ` (API error code ${envelopeCode})` : '';
+  throw new Error(`TikTok Ads API request failed (${response.status}): ${message}${codeSuffix}`);
+}