{"_id":"@cesteral/tiktok-mcp","_rev":"4-a6721292b195c20f8393d9f4cd8a12b7","name":"@cesteral/tiktok-mcp","dist-tags":{"latest":"1.3.0"},"versions":{"1.0.0":{"name":"@cesteral/tiktok-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","advertising","tiktok-ads"],"license":"Apache-2.0","_id":"@cesteral/tiktok-mcp@1.0.0","maintainers":[{"name":"dthorner","email":"daniel@cesteral.com"}],"homepage":"https://github.com/cesteral/mcp-open-advertising#readme","bugs":{"url":"https://github.com/cesteral/mcp-open-advertising/issues"},"bin":{"tiktok-mcp":"dist/index.js"},"dist":{"shasum":"373bf15c4aa15005043fa73969f13563cd204ccc","tarball":"https://registry.npmjs.org/@cesteral/tiktok-mcp/-/tiktok-mcp-1.0.0.tgz","fileCount":267,"integrity":"sha512-WHSRBwpqRBniTTInLrAppny+2iTElm+Rt1vaLg5L67+GkSEXyg1+5rynKliFBmICVNc++2goQ8RfA229eE58NQ==","signatures":[{"sig":"MEQCIFwnWVaQLy+oqFissEEpN0sh4QH1ZqUK5gRoVe4O3Nm/AiA87mR0i4cvQT0NP16fWShTy6fznz4vpJyFtA5+sIdEnQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":630531},"main":"./dist/index.js","type":"module","_from":"file:cesteral-tiktok-mcp-1.0.0.tgz","types":"./dist/index.d.ts","mcpName":"io.github.cesteral/tiktok-mcp","scripts":{"lint":"eslint src/","test":"vitest run","build":"tsc --build","clean":"rm -rf dist *.tsbuildinfo","start":"node dist/index.js","dev:http":"tsx watch src/index.ts","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"dthorner","email":"daniel@cesteral.com"},"_resolved":"/private/var/folders/bz/1h6614hx7t3frwb22plhcphsgw60rr/T/0514be4015285f8e1c5549da7d8306e9/cesteral-tiktok-mcp-1.0.0.tgz","_integrity":"sha512-WHSRBwpqRBniTTInLrAppny+2iTElm+Rt1vaLg5L67+GkSEXyg1+5rynKliFBmICVNc++2goQ8RfA229eE58NQ==","repository":{"url":"git+https://github.com/cesteral/mcp-open-advertising.git","type":"git","directory":"packages/tiktok-mcp"},"_npmVersion":"10.9.4","description":"TikTok Ads MCP Server - Campaign entity management and reporting via TikTok Marketing API v1.3","directories":{},"_nodeVersion":"22.21.0","dependencies":{"zod":"3.25.76","pino":"^10.1.0","@cesteral/shared":"1.0.0","@modelcontextprotocol/sdk":"1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","vitest":"^1.6.0","typescript":"^5.9.3","@types/node":"^20.17.6"},"_npmOperationalInternal":{"tmp":"tmp/tiktok-mcp_1.0.0_1779132118735_0.29843390715948037","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@cesteral/tiktok-mcp","version":"1.1.0","keywords":["mcp","model-context-protocol","advertising","tiktok-ads"],"license":"Apache-2.0","_id":"@cesteral/tiktok-mcp@1.1.0","maintainers":[{"name":"dthorner","email":"daniel@cesteral.com"}],"homepage":"https://github.com/cesteral/mcp-open-advertising#readme","bugs":{"url":"https://github.com/cesteral/mcp-open-advertising/issues"},"bin":{"tiktok-mcp":"dist/index.js"},"dist":{"shasum":"da44e07b0094faa31e8e5064537c3071799160e7","tarball":"https://registry.npmjs.org/@cesteral/tiktok-mcp/-/tiktok-mcp-1.1.0.tgz","fileCount":260,"integrity":"sha512-hkpNebPXC21k+2xJ3rms+o/c8TgltJAtSR0ROl8MgMnuGUpG6pJIw4mKnrdzPcdXl+DxAlmJflMb6u9C/hG3Tw==","signatures":[{"sig":"MEUCIEDPP8C968j3k5/qDk8JiTxN82B+IngbvXGxf84kBytFAiEA3rsLMdVCguggHQZ7QHLFd+O2HcDgnnVD8TD2q7pD4kg=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cesteral%2ftiktok-mcp@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":730478},"main":"./dist/index.js","type":"module","_from":"file:/tmp/tmp.9VJEooT4UT/cesteral-tiktok-mcp-1.1.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./testkit":{"types":"./dist/testkit/index.d.ts","import":"./dist/testkit/index.js"}},"mcpName":"io.github.cesteral/tiktok-mcp","scripts":{"lint":"eslint src/","test":"vitest run","build":"tsc --build","clean":"rm -rf dist *.tsbuildinfo","start":"node dist/index.js","dev:http":"tsx watch src/index.ts","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"dthorner","email":"daniel@cesteral.com"},"_resolved":"/tmp/tmp.9VJEooT4UT/cesteral-tiktok-mcp-1.1.0.tgz","_integrity":"sha512-hkpNebPXC21k+2xJ3rms+o/c8TgltJAtSR0ROl8MgMnuGUpG6pJIw4mKnrdzPcdXl+DxAlmJflMb6u9C/hG3Tw==","repository":{"url":"git+https://github.com/cesteral/mcp-open-advertising.git","type":"git","directory":"packages/tiktok-mcp"},"_npmVersion":"10.9.7","description":"TikTok Ads MCP Server - Campaign entity management and reporting via TikTok Marketing API v1.3","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"3.25.76","pino":"^10.1.0","@cesteral/shared":"1.1.0","@modelcontextprotocol/sdk":"1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","vitest":"^1.6.0","typescript":"^5.9.3","@types/node":"^20.17.6"},"_npmOperationalInternal":{"tmp":"tmp/tiktok-mcp_1.1.0_1779311731469_0.06535114721807256","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@cesteral/tiktok-mcp","version":"1.2.0","keywords":["mcp","model-context-protocol","advertising","tiktok-ads"],"license":"Apache-2.0","_id":"@cesteral/tiktok-mcp@1.2.0","maintainers":[{"name":"dthorner","email":"daniel@cesteral.com"}],"homepage":"https://github.com/cesteral/mcp-open-advertising#readme","bugs":{"url":"https://github.com/cesteral/mcp-open-advertising/issues"},"bin":{"tiktok-mcp":"dist/index.js"},"dist":{"shasum":"359747d78879b4bbb339c32bad742486173390ec","tarball":"https://registry.npmjs.org/@cesteral/tiktok-mcp/-/tiktok-mcp-1.2.0.tgz","fileCount":260,"integrity":"sha512-m40DaOyOr1On+iLmH37vXzOHP5fU8AfQ3vSKJwT1IMErLJ8fSaJ5aOFhOotcZib5YTXlT/0woAbTdcK0x5JDxg==","signatures":[{"sig":"MEUCIGXUfaycmKxH+jjVNE2KpqblonML7/7siQIecqTj+00FAiEA4i3K1rzwGmY05sYcK/hMzu90sHvmBUkmVyaGvPYHAKI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cesteral%2ftiktok-mcp@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":731547},"main":"./dist/index.js","type":"module","_from":"file:/tmp/tmp.DQ9QXkV3Jr/cesteral-tiktok-mcp-1.2.0.tgz","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./testkit":{"types":"./dist/testkit/index.d.ts","import":"./dist/testkit/index.js"}},"mcpName":"io.github.cesteral/tiktok-mcp","scripts":{"lint":"eslint src/","test":"vitest run","build":"tsc --build","clean":"rm -rf dist *.tsbuildinfo","start":"node dist/index.js","dev:http":"tsx watch src/index.ts","typecheck":"tsc --noEmit","test:coverage":"vitest run --coverage"},"_npmUser":{"name":"dthorner","email":"daniel@cesteral.com"},"_resolved":"/tmp/tmp.DQ9QXkV3Jr/cesteral-tiktok-mcp-1.2.0.tgz","_integrity":"sha512-m40DaOyOr1On+iLmH37vXzOHP5fU8AfQ3vSKJwT1IMErLJ8fSaJ5aOFhOotcZib5YTXlT/0woAbTdcK0x5JDxg==","repository":{"url":"git+https://github.com/cesteral/mcp-open-advertising.git","type":"git","directory":"packages/tiktok-mcp"},"_npmVersion":"10.9.8","description":"TikTok Ads MCP Server - Campaign entity management and reporting via TikTok Marketing API v1.3","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"3.25.76","pino":"^10.1.0","@cesteral/shared":"1.1.0","@modelcontextprotocol/sdk":"1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.6","vitest":"^1.6.0","typescript":"^5.9.3","@types/node":"^20.17.6"},"_npmOperationalInternal":{"tmp":"tmp/tiktok-mcp_1.2.0_1780339814188_0.805661403824887","host":"s3://npm-registry-packages-npm-production"}},"1.3.0":{"name":"@cesteral/tiktok-mcp","mcpName":"io.github.cesteral/tiktok-mcp","version":"1.3.0","description":"TikTok Ads MCP Server - Campaign entity management and reporting via TikTok Marketing API v1.3","license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/cesteral/mcp-open-advertising.git","directory":"packages/tiktok-mcp"},"homepage":"https://github.com/cesteral/mcp-open-advertising#readme","keywords":["mcp","model-context-protocol","advertising","tiktok-ads"],"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./testkit":{"types":"./dist/testkit/index.d.ts","import":"./dist/testkit/index.js"}},"bin":{"tiktok-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"dependencies":{"@modelcontextprotocol/sdk":"1.27.1","pino":"^10.1.0","zod":"3.25.76","@cesteral/shared":"1.2.0"},"devDependencies":{"@types/node":"^20.17.6","tsx":"^4.20.6","typescript":"^5.9.3","vitest":"^1.6.0"},"scripts":{"build":"tsc --build","clean":"rm -rf dist *.tsbuildinfo","dev:http":"tsx watch src/index.ts","start":"node dist/index.js","typecheck":"tsc --noEmit","lint":"eslint src/","test":"vitest run","test:coverage":"vitest run --coverage"},"_id":"@cesteral/tiktok-mcp@1.3.0","bugs":{"url":"https://github.com/cesteral/mcp-open-advertising/issues"},"_integrity":"sha512-ERIlUVQEr/GyNiPA2FO2SK74TthFOWbm23BqWnsf98SAcMAfTziT5ctRwuF8Zp+NfVl5CXm/+N0hyieBIyw2tg==","_resolved":"/tmp/5530e0fd6a086995bf1cc0ba3fff02a9/cesteral-tiktok-mcp-1.3.0.tgz","_from":"file:cesteral-tiktok-mcp-1.3.0.tgz","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-ERIlUVQEr/GyNiPA2FO2SK74TthFOWbm23BqWnsf98SAcMAfTziT5ctRwuF8Zp+NfVl5CXm/+N0hyieBIyw2tg==","shasum":"78eb3ceb3006d36484768a56c699440adbe52edf","tarball":"https://registry.npmjs.org/@cesteral/tiktok-mcp/-/tiktok-mcp-1.3.0.tgz","fileCount":260,"unpackedSize":778089,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@cesteral%2ftiktok-mcp@1.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/eXXej8bx+R5NFKCgQkcoStIlr/UdPKBjooTGAnRMYAIhAPX9khIamUojrDC0OrJwuf4lp1kHTGalCgySmBYIprJR"}]},"_npmUser":{"name":"dthorner","email":"daniel@cesteral.com"},"directories":{},"maintainers":[{"name":"dthorner","email":"daniel@cesteral.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tiktok-mcp_1.3.0_1781104176510_0.0743728447025751"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-18T19:21:58.573Z","modified":"2026-06-10T15:09:37.017Z","1.0.0":"2026-05-18T19:21:58.875Z","1.1.0":"2026-05-20T21:15:31.607Z","1.2.0":"2026-06-01T18:50:14.373Z","1.3.0":"2026-06-10T15:09:36.710Z"},"bugs":{"url":"https://github.com/cesteral/mcp-open-advertising/issues"},"license":"Apache-2.0","homepage":"https://github.com/cesteral/mcp-open-advertising#readme","keywords":["mcp","model-context-protocol","advertising","tiktok-ads"],"repository":{"type":"git","url":"git+https://github.com/cesteral/mcp-open-advertising.git","directory":"packages/tiktok-mcp"},"description":"TikTok Ads MCP Server - Campaign entity management and reporting via TikTok Marketing API v1.3","maintainers":[{"name":"dthorner","email":"daniel@cesteral.com"}],"readme":"# @cesteral/tiktok-mcp\n\nTikTok Ads MCP Server - Campaign management and reporting via TikTok Marketing API v1.3.\n\n## Purpose\n\nManagement server for TikTok Ads. Provides full CRUD operations, async\nreporting, targeting discovery, bulk operations, and specialized features like\nentity duplication and audience estimation. Designed for AI agents to manage\nTikTok Ads campaigns programmatically through the Model Context Protocol with\nper-session Bearer token authentication.\n\n## Features\n\n- **Per-session Bearer token auth** via `TikTokBearerAuthStrategy` (validates tokens and extracts advertiser ID)\n- **Streamable HTTP + stdio transports** via Hono + `@hono/mcp`\n- **OpenTelemetry** instrumentation for traces and metrics\n- **Rate limiting** via shared `RateLimiter` class (100/min default)\n- **Structured logging** via Pino\n- **Automatic `advertiser_id` injection** into GET query params and POST request bodies\n\n## MCP Tools\n\n### Core CRUD\n\n#### 1. `tiktok_list_entities`\n\nList TikTok Ads entities with page-based pagination and optional filtering.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entity to list\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `filters` (object, optional): Filter criteria for the entity list\n- `page` (number, optional): Page number for pagination\n- `pageSize` (number, optional): Results per page\n\n#### 2. `tiktok_get_entity`\n\nGet a single TikTok Ads entity by ID.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entity to retrieve\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `entityId` (string, required): The entity ID\n\n#### 3. `tiktok_create_entity`\n\nCreate a new TikTok Ads entity.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entity to create\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `data` (object, required): Entity fields as key-value pairs\n\n#### 4. `tiktok_update_entity`\n\nUpdate an existing TikTok Ads entity.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entity to update\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `entityId` (string, required): The entity ID to update\n- `data` (object, required): Fields to update as key-value pairs\n\n#### 5. `tiktok_delete_entity`\n\nDelete TikTok Ads entities.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entities to delete\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `entityIds` (string[], required): Entity IDs to delete (max 20)\n\n### Account\n\n#### 6. `tiktok_list_advertisers`\n\nList advertiser accounts accessible to the authenticated user.\n\n**Parameters:** _(none)_\n\n### Reporting\n\n> All TikTok reporting tools return data using the shared bounded report-view contract: `mode` (`\"summary\"` default — headers + counts + 10-row preview, or `\"rows\"` for a paginated rows page), `columns` (project to selected columns), `offset` (zero-based pagination), and `maxRows` (page size; default 10 for summary, 50 for rows; hard cap 200).\n\n#### 7. `tiktok_get_report`\n\nSubmit an async report and download results once complete.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `dimensions` (string[], required): Report dimensions (e.g., `campaign_id`, `adgroup_id`)\n- `metrics` (string[], required): Metrics to include (e.g., `spend`, `impressions`, `clicks`)\n- `startDate` (string, required): Start date (YYYY-MM-DD)\n- `endDate` (string, required): End date (YYYY-MM-DD)\n- `mode`, `columns`, `offset`, `maxRows` (optional): Bounded report-view params (see note above)\n\n#### 8. `tiktok_get_report_breakdowns`\n\nSubmit a report with additional breakdown dimensions.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `dimensions` (string[], required): Primary dimensions\n- `breakdowns` (string[], required): Breakdown dimensions (e.g., `age`, `gender`, `country`)\n- `metrics` (string[], required): Metrics to include\n- `startDate` (string, required): Start date (YYYY-MM-DD)\n- `endDate` (string, required): End date (YYYY-MM-DD)\n- `mode`, `columns`, `offset`, `maxRows` (optional): Bounded report-view params (see note above)\n\n#### 9. `tiktok_submit_report`\n\nSubmit an async report without waiting for completion (non-blocking).\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `dimensions` (string[], required): Report dimensions\n- `metrics` (string[], required): Metrics to include\n- `startDate` (string, required): Start date (YYYY-MM-DD)\n- `endDate` (string, required): End date (YYYY-MM-DD)\n\n#### 10. `tiktok_check_report_status`\n\nSingle status check for a submitted report.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `taskId` (string, required): Report task ID from submit\n\n#### 11. `tiktok_download_report`\n\nDownload and parse report CSV from URL.\n\n**Parameters:**\n\n- `downloadUrl` (string, required): Report download URL\n- `mode`, `columns`, `offset`, `maxRows` (optional): Bounded report-view params (see note above the reporting tools)\n\n### Bulk Operations\n\n#### 12. `tiktok_bulk_update_status`\n\nBatch enable, disable, or delete multiple entities.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entities to update\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `entityIds` (string[], required): Entity IDs to update (max 50)\n- `operationStatus` (string, required): `ENABLE`, `DISABLE`, or `DELETE`\n\n#### 13. `tiktok_bulk_create_entities`\n\nBatch create multiple entities of the same type.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entities to create\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `items` (array, required): Array of entity data objects (max 50)\n\n#### 14. `tiktok_bulk_update_entities`\n\nBatch update multiple entities with individual data payloads.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entities to update\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `items` (array, required): Array of update items (max 50), each with entity ID and data\n\n### Bid Adjustment\n\n#### 15. `tiktok_adjust_bids`\n\nBatch adjust ad group bid prices with safe read-modify-write pattern.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `adjustments` (array, required): Array of bid adjustments, each with ad group ID, adjustment type, and value\n\n### Targeting\n\n#### 16. `tiktok_search_targeting`\n\nSearch for targeting options (interest categories, behaviors, demographics) by keyword.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `targetingType` (string, required): Type of targeting to search\n- `query` (string, optional): Search keyword\n\n#### 17. `tiktok_get_targeting_options`\n\nBrowse available targeting categories.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `targetingType` (string, optional): Filter by targeting type\n\n### Specialized\n\n#### 18. `tiktok_duplicate_entity`\n\nDuplicate a campaign, ad group, or ad.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entity to duplicate (`campaign`, `adGroup`, `ad`)\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `entityId` (string, required): ID of the entity to duplicate\n- `options` (object, optional): Duplication options (e.g., rename prefix/suffix)\n\n#### 19. `tiktok_get_audience_estimate`\n\nGet estimated audience size for a targeting configuration.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `targetingConfig` (object, required): Targeting specification for estimation\n\n#### 20. `tiktok_get_ad_preview`\n\nGet ad preview for video or image ads.\n\n**Parameters:**\n\n- `advertiserId` (string, required): TikTok Advertiser ID\n- `adId` (string, required): Ad ID to preview\n- `adFormat` (string, optional): Ad format for preview rendering\n\n### Validation\n\n#### 21. `tiktok_validate_entity`\n\nClient-side validation of entity payloads without making API calls.\n\n**Parameters:**\n\n- `entityType` (string, required): Type of entity to validate\n- `mode` (string, required): Validation mode (`create` or `update`)\n- `data` (object, required): Entity data to validate\n\n## Supported Entity Types\n\n| Entity Type | API Object | Notes                                           |\n| ----------- | ---------- | ----------------------------------------------- |\n| `campaign`  | Campaign   | Top-level entity under advertiser account       |\n| `adGroup`   | Ad Group   | Targeting, budget, schedule, bidding, placement |\n| `ad`        | Ad         | Links creative content to ad group              |\n| `creative`  | Creative   | Video/image creative assets                     |\n\n**Entity Hierarchy:** Advertiser > Campaign > Ad Group > Ad (+ Creatives)\n\n## Current Status\n\n**Phase: Production-Ready**\n\nAll listed tools are fully implemented using TikTok Marketing API v1.3 with\nBearer token authentication, async reporting, and targeting discovery.\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Run in development mode\npnpm run dev:http\n\n# Build\npnpm run build\n\n# Start production server\npnpm run start\n\n# Type check\npnpm run typecheck\n```\n\n## Environment Variables\n\n- `TIKTOK_MCP_PORT`: Server port (default: 3007)\n- `TIKTOK_MCP_HOST`: Server host (default: `127.0.0.1` in development, `0.0.0.0` in production)\n- `MCP_AUTH_MODE`: Authentication mode - `tiktok-bearer` (default), `jwt`, or `none`\n- `MCP_AUTH_SECRET_KEY`: Required when `MCP_AUTH_MODE=jwt`\n- `TIKTOK_API_BASE_URL`: TikTok Business API base URL (default: `https://business-api.tiktok.com`)\n- `TIKTOK_API_VERSION`: API version (default: `v1.3`)\n- `TIKTOK_RATE_LIMIT_PER_MINUTE`: Rate limit ceiling (default: 100)\n- `TIKTOK_ACCESS_TOKEN`: Access token for stdio mode\n- `TIKTOK_ADVERTISER_ID`: Advertiser ID for stdio mode\n\n## Architecture\n\n### Key Components\n\n- **`TikTokHttpClient`** - HTTP client for TikTok Marketing API v1.3\n- **`TikTokService`** - CRUD, bulk ops, duplication, targeting, audience estimates, ad previews\n- **`TikTokReportingService`** - Async report submission, polling, and download\n- **`TikTokBearerAuthStrategy`** - Bearer token + advertiser ID auth\n- **`TikTokAuthAdapter`** - Token + advertiser ID management for per-session API calls\n- **`SessionServiceStore`** - Per-session service instances keyed by session ID\n\n### Key Gotchas\n\n- `advertiser_id` is automatically injected into GET query params and POST request bodies\n- Uses page-based pagination (`page`/`page_size`) not cursor-based\n- Reporting is async: submit report -> poll for completion -> download results\n- Delete operations accept max 20 entity IDs per call\n- `DISABLE` status is used instead of `PAUSED` (TikTok-specific terminology)\n\n### Transport\n\nStreamable HTTP via Hono + `@hono/mcp`. Health check at `/health`.\n\n## Contributing\n\nSee root [CLAUDE.md](../../CLAUDE.md) for development guidelines, build system details, and monorepo conventions. See the [root README](../../README.md) for full architecture context.\n\n---\n\n## Get Started\n\n**Self-host**: Follow the [deployment guide](../../docs/guides/deployment-instructions.md) to run this server on your own infrastructure.\n\n**Cesteral Intelligence**: [Request access](https://cesteral.com/integrations/tiktok-ads?utm_source=github&utm_medium=package-readme&utm_campaign=tiktok-mcp) -- governed execution with credential brokering, approvals, audit, and multi-tenant access.\n\n**Book a workflow demo**: [See it in action](mailto:sales@cesteral.com?subject=Workflow%20demo%20-%20TikTok%20Ads%20MCP) with your own ad accounts.\n\n**Compare options**: [OSS connectors vs Cesteral Intelligence](https://cesteral.com/compare?utm_source=github&utm_medium=package-readme&utm_campaign=tiktok-mcp)\n\n## License\n\nApache License 2.0 — see [LICENSE](../../LICENSE.md) for details. This package is part of Cesteral's open-source connector layer; managed hosting and higher-level governance features live outside this repository.\n","readmeFilename":"README.md"}