@channel47/tiktok-ads-mcp 0.1.0

package/server/index.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { validateEnvironment } from './auth.js';
+import { listAccounts } from './tools/list-accounts.js';
+import { query } from './tools/query.js';
+import { report } from './tools/report.js';
+import { mutate } from './tools/mutate.js';
+import { getPromptsList, renderPrompt } from './prompts/templates.js';
+import { getResourcesList, readResource } from './resources/index.js';
+
+const SERVER_NAME = 'tiktok-ads-mcp';
+const SERVER_VERSION = '0.1.0';
+const READ_ONLY = process.env.TIKTOK_ADS_READ_ONLY === 'true';
+
+const ALL_TOOLS = [
+  {
+    name: 'list_accounts',
+    description: 'List accessible TikTok ad accounts (advertisers) with name, status, currency, and timezone. Discovers advertiser ids via /oauth2/advertiser/get/ when TIKTOK_ADS_APP_ID and TIKTOK_ADS_APP_SECRET are set; otherwise pass advertiser_ids or set TIKTOK_ADS_ADVERTISER_ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        advertiser_ids: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Explicit advertiser ids to look up (skips oauth2 discovery)'
+        }
+      }
+    }
+  },
+  {
+    name: 'query',
+    description: 'Query campaigns, adgroups, or ads from the TikTok Business API with optional filtering, field selection, and pagination.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        advertiser_id: {
+          type: 'string',
+          description: 'TikTok advertiser ID (defaults to TIKTOK_ADS_ADVERTISER_ID)'
+        },
+        entity: {
+          type: 'string',
+          enum: ['campaigns', 'adgroups', 'ads'],
+          description: 'Entity type to query'
+        },
+        fields: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'Optional fields selection. Defaults to entity-specific presets.'
+        },
+        filtering: {
+          type: 'object',
+          description: 'Optional TikTok filtering object (e.g. { "campaign_ids": ["123"], "primary_status": "STATUS_DELIVERY_OK" })'
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 1000,
+          description: 'Maximum rows to return (default: 100, max: 1000)'
+        }
+      },
+      required: ['entity']
+    }
+  },
+  {
+    name: 'report',
+    description: 'Run a synchronous TikTok integrated report (GET /report/integrated/get/) with dimensions, metrics, and a date range or lifetime scope. Rows are returned with dimensions and metrics flattened together.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        advertiser_id: {
+          type: 'string',
+          description: 'TikTok advertiser ID (defaults to TIKTOK_ADS_ADVERTISER_ID)'
+        },
+        report_type: {
+          type: 'string',
+          enum: ['BASIC', 'AUDIENCE'],
+          description: 'Report type (default: BASIC)'
+        },
+        data_level: {
+          type: 'string',
+          enum: ['AUCTION_ADVERTISER', 'AUCTION_CAMPAIGN', 'AUCTION_ADGROUP', 'AUCTION_AD'],
+          description: 'Aggregation level (default: AUCTION_CAMPAIGN)'
+        },
+        dimensions: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Report dimensions. Defaults to the data_level id dimension plus stat_time_day (id dimension only when lifetime=true).'
+        },
+        metrics: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Report metrics (default: spend, impressions, clicks, ctr, cpc, cpm, conversion, cost_per_conversion, conversion_rate)'
+        },
+        start_date: {
+          type: 'string',
+          description: 'Start date YYYY-MM-DD (defaults to 7 days ago when lifetime is false)'
+        },
+        end_date: {
+          type: 'string',
+          description: 'End date YYYY-MM-DD (defaults to today UTC when lifetime is false)'
+        },
+        lifetime: {
+          type: 'boolean',
+          description: 'Query lifetime metrics instead of a date range (default: false; excludes stat_time dimensions)'
+        },
+        filtering: {
+          type: 'array',
+          items: { type: 'object' },
+          description: 'Optional filter clauses: [{ "field_name", "filter_type", "filter_value" }]'
+        },
+        order_field: {
+          type: 'string',
+          description: 'Optional metric/dimension to sort by (e.g. spend)'
+        },
+        order_type: {
+          type: 'string',
+          enum: ['ASC', 'DESC'],
+          description: 'Sort direction when order_field is set (default: DESC)'
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 1000,
+          description: 'Maximum rows to return (default: 100, max: 1000)'
+        }
+      }
+    }
+  },
+  {
+    name: 'mutate',
+    description: 'Execute create/update/pause/enable/delete operations for campaign, adgroup, and ad entities. dry_run defaults to true and performs local validation plus a preview of the exact requests (TikTok has no server-side validate-only mode). Campaign and adgroup creates default operation_status to DISABLE (paused) for safety. DELETE is permanent and unrecoverable — prefer pause. Ad updates take the full /ad/update/ body in params (ads are identified via creatives[].ad_id).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        advertiser_id: {
+          type: 'string',
+          description: 'TikTok advertiser ID (defaults to TIKTOK_ADS_ADVERTISER_ID)'
+        },
+        operations: {
+          type: 'array',
+          description: 'Array of operation objects: { entity, action, id?, params? }',
+          items: {
+            type: 'object'
+          }
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'Validate locally and preview requests only (default: true)',
+          default: true
+        },
+        partial_failure: {
+          type: 'boolean',
+          description: 'Continue executing later operations when one fails (default: true)',
+          default: true
+        }
+      },
+      required: ['operations']
+    }
+  }
+];
+
+const TOOLS = READ_ONLY ? ALL_TOOLS.filter((tool) => tool.name !== 'mutate') : ALL_TOOLS;
+
+const envStatus = validateEnvironment();
+if (!envStatus.valid) {
+  console.error(`Missing required environment variables: ${envStatus.missing.join(', ')}`);
+  process.exit(1);
+}
+
+if (READ_ONLY) {
+  console.error('Read-only mode enabled — mutate tool disabled');
+}
+
+const server = new Server(
+  {
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+      resources: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: params } = request.params;
+
+  if (name === 'list_accounts') {
+    return listAccounts(params);
+  }
+
+  if (name === 'query') {
+    return query(params);
+  }
+
+  if (name === 'report') {
+    return report(params);
+  }
+
+  if (name === 'mutate') {
+    if (READ_ONLY) {
+      throw new Error('mutate is disabled in read-only mode (TIKTOK_ADS_READ_ONLY=true)');
+    }
+    return mutate(params);
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: getPromptsList() }));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => (
+  renderPrompt(request.params.name, request.params.arguments || {})
+));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: getResourcesList() }));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => readResource(request.params.uri));
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});

package/server/prompts/templates.js

@@ -0,0 +1,127 @@
+export const PROMPT_TEMPLATES = {
+  spend_pacing_check: {
+    name: 'spend_pacing_check',
+    description: 'Check campaign pacing against recent spend and budget signals',
+    arguments: [
+      {
+        name: 'advertiser_id',
+        description: 'TikTok advertiser ID',
+        required: true
+      },
+      {
+        name: 'lookback_days',
+        description: 'Number of trailing days to analyze',
+        required: false,
+        default: '7'
+      }
+    ],
+    template: `Run a spend pacing check for TikTok advertiser {{advertiser_id}} over the last {{lookback_days}} days:
+
+1. Pull campaign-level report rows (spend, impressions, clicks, conversion, cost_per_conversion) with stat_time_day.
+2. Pull campaign budgets and budget_mode via query.
+3. Compare daily spend velocity to available daily/lifetime budgets.
+4. Flag campaigns underpacing and overpacing.
+5. Highlight campaigns spending with weak conversion signals.
+6. Return top pacing issues and recommended budget actions.`,
+    requiredTools: ['query', 'report']
+  },
+  creative_fatigue_check: {
+    name: 'creative_fatigue_check',
+    description: 'Check for ad creative fatigue signals and propose refresh priorities',
+    arguments: [
+      {
+        name: 'advertiser_id',
+        description: 'TikTok advertiser ID',
+        required: true
+      },
+      {
+        name: 'lookback_days',
+        description: 'Number of trailing days to analyze',
+        required: false,
+        default: '14'
+      }
+    ],
+    template: `Run a creative fatigue analysis for TikTok advertiser {{advertiser_id}} using the last {{lookback_days}} days of data:
+
+1. Pull ad-level report rows (spend, impressions, clicks, ctr, conversion) with stat_time_day.
+2. Flag ads with declining CTR and rising cost_per_conversion week over week.
+3. Group fatigued ads by campaign and ad group.
+4. Identify top creatives to refresh first by wasted spend.
+5. Return prioritized creative refresh recommendations with rationale.`,
+    requiredTools: ['query', 'report']
+  },
+  account_performance_audit: {
+    name: 'account_performance_audit',
+    description: 'Audit overall account structure and performance for quick wins',
+    arguments: [
+      {
+        name: 'advertiser_id',
+        description: 'TikTok advertiser ID',
+        required: true
+      },
+      {
+        name: 'lookback_days',
+        description: 'Number of trailing days to analyze',
+        required: false,
+        default: '30'
+      }
+    ],
+    template: `Run an account performance audit for TikTok advertiser {{advertiser_id}} over the last {{lookback_days}} days:
+
+1. List campaigns, ad groups, and ads with statuses via query.
+2. Pull campaign- and adgroup-level report rows (spend, impressions, clicks, ctr, cpc, conversion, cost_per_conversion).
+3. Identify paused or rejected entities blocking delivery (secondary_status).
+4. Rank campaigns by efficiency (cost_per_conversion) and spend concentration.
+5. Flag structural issues (single-ad ad groups, overlapping schedules, exhausted budgets).
+6. Return a prioritized list of quick wins with expected impact.`,
+    requiredTools: ['query', 'report']
+  }
+};
+
+export function getPromptDefinition(name) {
+  return PROMPT_TEMPLATES[name] || null;
+}
+
+export function getPromptsList() {
+  return Object.values(PROMPT_TEMPLATES).map((prompt) => ({
+    name: prompt.name,
+    description: prompt.description,
+    arguments: prompt.arguments
+  }));
+}
+
+export function renderPrompt(name, args = {}) {
+  const template = PROMPT_TEMPLATES[name];
+  if (!template) {
+    throw new Error(`Unknown prompt: ${name}. Available prompts: ${Object.keys(PROMPT_TEMPLATES).join(', ')}`);
+  }
+
+  const missing = template.arguments
+    .filter((argument) => argument.required && !args[argument.name])
+    .map((argument) => argument.name);
+
+  if (missing.length > 0) {
+    throw new Error(`Missing required arguments for prompt "${name}": ${missing.join(', ')}`);
+  }
+
+  let text = template.template;
+
+  for (const argument of template.arguments) {
+    const value = args[argument.name] ?? argument.default;
+    if (value !== undefined) {
+      text = text.replace(new RegExp(`\\{\\{${argument.name}\\}\\}`, 'g'), String(value));
+    }
+  }
+
+  return {
+    messages: [
+      {
+        role: 'user',
+        content: {
+          type: 'text',
+          text
+        }
+      }
+    ]
+  };
+}

package/server/resources/business-api-reference.md

@@ -0,0 +1,72 @@
+# TikTok Business API Quick Reference
+
+## Base URL
+
+`https://business-api.tiktok.com/open_api/v1.3`
+
+## Authentication
+
+- Auth is provided via the `Access-Token` request header (not `Authorization: Bearer`)
+- This server reads the token from `TIKTOK_ADS_ACCESS_TOKEN`
+- Tokens issued for the Business API are long-lived; no refresh flow in v1
+- `TIKTOK_ADS_APP_ID` + `TIKTOK_ADS_APP_SECRET` (developer app credentials) are only needed for advertiser discovery via `/oauth2/advertiser/get/`
+
+## Response Envelope
+
+Every response — including errors — is normally HTTP `200` with:
+
+```json
+{
+  "code": 0,
+  "message": "OK",
+  "request_id": "...",
+  "data": { }
+}
+```
+
+- `code: 0` means success; any non-zero `code` is an error
+- This server converts non-zero codes into thrown errors that include the code and message
+- List endpoints return `data.list` plus `data.page_info { page, page_size, total_number, total_page }`
+
+## Account Discovery
+
+- Authorized advertisers: `GET /oauth2/advertiser/get/` with `app_id` and `secret` query params (plus `Access-Token` header). Returns `data.list` of `{ advertiser_id, advertiser_name }`
+- Account details: `GET /advertiser/info/` with `advertiser_ids` (JSON-encoded array, max 100 ids) and optional `fields` (JSON-encoded array, e.g. `name`, `status`, `currency`, `timezone`, `company`, `country`, `create_time`)
+
+## Query Endpoints (by Advertiser)
+
+- Campaigns: `GET /campaign/get/`
+- Ad groups: `GET /adgroup/get/`
+- Ads: `GET /ad/get/`
+
+Useful query params:
+
+- `advertiser_id` (required)
+- `fields`: JSON-encoded array of field names
+- `filtering`: JSON-encoded object (e.g. `{"campaign_ids": ["123"], "primary_status": "STATUS_DELIVERY_OK"}`)
+- `page` (default 1) and `page_size` (default 10, max 1000)
+
+Complex GET params (`fields`, `filtering`, `dimensions`, `metrics`, `advertiser_ids`) must be JSON-encoded strings in the query string.
+
+## Mutations
+
+All writes are `POST` with a JSON body that includes `advertiser_id`:
+
+- Create: `POST /campaign/create/`, `POST /adgroup/create/`, `POST /ad/create/`
+- Update: `POST /campaign/update/` (`campaign_id`), `POST /adgroup/update/` (`adgroup_id`), `POST /ad/update/` (identifies ads via `creatives[].ad_id`)
+- Status: `POST /campaign/status/update/` (`campaign_ids`), `POST /adgroup/status/update/` (`adgroup_ids`), `POST /ad/status/update/` (`ad_ids`) with `operation_status`: `ENABLE`, `DISABLE`, or `DELETE` (max 100 ids per call)
+
+Notes:
+
+- `/campaign/create/` requires `campaign_name` and `objective_type`; `operation_status` defaults to `ENABLE` server-side — this server defaults it to `DISABLE` (paused)
+- `/adgroup/create/` requires `campaign_id`, `adgroup_name`, `billing_event`, `budget`, `budget_mode`, `optimization_goal`, `pacing`, `schedule_type`, `schedule_start_time`
+- `/ad/create/` requires `adgroup_id` and a `creatives` array; there is no top-level `operation_status`
+- `DELETE` via status update is permanent — prefer `DISABLE` (pause)
+- There is no validate-only/dry-run mode in the API; this server's dry run previews requests locally
+
+## Error Handling
+
+- Non-zero `code` on HTTP 200 is an API error (message in `message`)
+- `code 40100` indicates rate limiting (see the rate limits resource)
+- Common auth errors: invalid/expired token, advertiser not authorized for the token
+- Budgets and money metrics are denominated in the advertiser account currency (major units)

package/server/resources/index.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Static list of resource documents exposed by the server.
+ */
+export const RESOURCES = [
+  {
+    uri: 'tiktokads://reference',
+    name: 'TikTok Business API Reference',
+    description: 'Core Business API endpoints, request conventions, and error handling notes for TikTok Ads workflows',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'tiktokads://reporting',
+    name: 'TikTok Ads Reporting Reference',
+    description: 'Integrated report dimensions, metrics, data levels, and date handling',
+    mimeType: 'text/markdown'
+  },
+  {
+    uri: 'tiktokads://rate-limits',
+    name: 'TikTok Ads Rate Limits and Quotas',
+    description: 'Rate limiting behavior, backoff guidance, and operational recommendations',
+    mimeType: 'text/markdown'
+  }
+];
+
+const RESOURCE_FILE_MAP = {
+  'tiktokads://reference': 'business-api-reference.md',
+  'tiktokads://reporting': 'reporting-reference.md',
+  'tiktokads://rate-limits': 'rate-limits-and-quotas.md'
+};
+
+export function getResourcesList() {
+  return RESOURCES;
+}
+
+/**
+ * Read a resource document by URI.
+ * @param {string} uri
+ * @returns {{ contents: Array<{ uri: string, mimeType: string, text: string }> }}
+ */
+export function readResource(uri) {
+  const filename = RESOURCE_FILE_MAP[uri];
+  if (!filename) {
+    throw new Error(`Unknown resource: ${uri}. Available: ${Object.keys(RESOURCE_FILE_MAP).join(', ')}`);
+  }
+
+  const filePath = join(__dirname, filename);
+  const content = readFileSync(filePath, 'utf8');
+
+  return {
+    contents: [
+      {
+        uri,
+        mimeType: 'text/markdown',
+        text: content
+      }
+    ]
+  };
+}

package/server/resources/rate-limits-and-quotas.md

@@ -0,0 +1,39 @@
+# TikTok Ads Rate Limits and Quotas
+
+The TikTok Business API enforces per-app QPS (queries per second) limits. Limits vary by endpoint tier and the access level of your developer app; they are not published as fixed per-endpoint numbers.
+
+## Throttling Signals
+
+- API error `code 40100` ("Too many requests") in the response envelope — usually still HTTP `200`
+- HTTP `429` at the transport level
+
+## What This MCP Server Does
+
+- Treats HTTP `429` and envelope error code `40100` as throttling signals.
+- Reads the `Retry-After` response header when available.
+- Falls back to `60` seconds if `Retry-After` is missing or invalid.
+- Retries throttled requests once.
+
+## Backoff Behavior
+
+`Retry-After` values may be:
+
+- Integer seconds (for example `7`)
+- HTTP date string
+
+The server converts this to milliseconds and sleeps before a single retry.
+
+## Timeout Behavior
+
+- Requests use a default timeout of `30000` ms.
+- Override with `TIKTOK_ADS_REQUEST_TIMEOUT_MS` environment variable.
+- Timeout errors are surfaced as request failures so callers can retry or degrade gracefully.
+
+## Operational Guidance
+
+- Keep requested field, dimension, and metric sets narrow.
+- Use `limit` deliberately and paginate only as needed (`page_size` max 1000).
+- Batch id lookups: `/advertiser/info/` accepts up to 100 ids, status updates up to 100 ids per call.
+- Avoid broad fan-out query loops across many advertisers at once.
+- Cache read-heavy metadata (advertiser and entity lists) where possible.
+- Stagger high-volume reporting jobs to reduce burst pressure.

package/server/resources/reporting-reference.md

@@ -0,0 +1,60 @@
+# TikTok Ads Reporting Reference
+
+The `report` tool wraps the synchronous integrated report endpoint:
+
+`GET /report/integrated/get/`
+
+## Report Types
+
+- `BASIC` (default): performance metrics by advertiser/campaign/adgroup/ad
+- `AUDIENCE`: performance broken down by audience dimensions (age, gender, country, etc.)
+
+The API also supports `PLAYABLE_MATERIAL`, `CATALOG`, and `BC` report types; this server intentionally exposes only `BASIC` and `AUDIENCE`.
+
+## Data Levels
+
+`data_level` controls aggregation and must match the id dimension used:
+
+| data_level | id dimension |
+|------------|--------------|
+| `AUCTION_ADVERTISER` | `advertiser_id` |
+| `AUCTION_CAMPAIGN` | `campaign_id` |
+| `AUCTION_ADGROUP` | `adgroup_id` |
+| `AUCTION_AD` | `ad_id` |
+
+## Dimensions
+
+- Id dimensions: `advertiser_id`, `campaign_id`, `adgroup_id`, `ad_id`
+- Time dimensions: `stat_time_day`, `stat_time_hour` (not allowed with lifetime queries)
+- Audience dimensions (`report_type: AUDIENCE`): `age`, `gender`, `country_code`, `language`, `platform`, `ac`
+
+Default in this server: the data_level id dimension plus `stat_time_day` (id dimension only when `lifetime: true`).
+
+## Common BASIC Metrics
+
+- Cost: `spend`, `cpc`, `cpm`
+- Delivery: `impressions`, `clicks`, `ctr`, `reach`, `frequency`, `cost_per_1000_reached`
+- Conversion: `conversion`, `cost_per_conversion`, `conversion_rate`, `real_time_conversion`
+- On-platform result: `result`, `cost_per_result`, `result_rate`
+- Video: `video_play_actions`, `video_watched_2s`, `video_watched_6s`, `average_video_play`
+- Engagement: `likes`, `comments`, `shares`, `follows`, `profile_visits`
+
+Note: the conversion metric is `conversion` (singular). Attribution metrics like `skan_*` exist for iOS campaigns.
+
+## Date Handling
+
+- `start_date` / `end_date` in `YYYY-MM-DD`, interpreted in the advertiser account timezone
+- Or `query_lifetime: true` for lifetime metrics (mutually exclusive with dates and `stat_time_*` dimensions)
+- This server defaults to the trailing 7 days (UTC) when no dates are given
+
+## Filtering and Sorting
+
+- `filtering`: JSON-encoded array of clauses, e.g.
+  `[{"field_name": "campaign_ids", "filter_type": "IN", "filter_value": "[\"123\"]"}]`
+- `order_field` + `order_type` (`ASC` / `DESC`) sort results server-side
+
+## Pagination
+
+- `page` (starts at 1) and `page_size` (max 1000)
+- Responses include `data.page_info { page, page_size, total_number, total_page }`
+- Rows arrive as `{ dimensions: {...}, metrics: {...} }`; this server flattens each row into a single object