tiktok-ads
Connects to TikTok for Business Ads via OAuth and the official Ads MCP, enabling account discovery, GMV Max reporting, campaign and creative-level reports, SKU/product metrics, report export to Excel, and local monitoring dashboards for TikTok ad performance.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
TikTok Ads Agent Kit · dsh-plugin-tiktok-ads
一套给 AI 用的 TikTok 广告数据工具:OAuth 授权 → 官方 Ads MCP 直连 → 广告组/素材/SKU 报表 → 实时盯盘面板 → Excel 导出。
三种接入方式:DSH 插件、命令行 CLI、stdio MCP Server。零运行时依赖,只要 Node.js ≥ 22。
广告账户 ──OAuth(PKCE)──▶ TikTok for Business MCP ──▶ 本工具 ──▶ AI / 面板 / Excel联系作者
互相学习,共同富裕。
有问题或想法,扫码加飞书聊:
备注「TikTok 广告工具」即可。
Related MCP server: meta-ads-mcp
直接打开面板(不开 DSH)
面板是一个本地网页,两种打开方式:
方式 | 地址 | 说明 |
双击桌面「TikTok广告监控面板」 | 启动 | |
DSH 运行时 | 插件随 DSH 自动启动,关掉 DSH 就没了 |
前提:本机代理要开着(默认读 Windows 系统代理,通常是 127.0.0.1:7890)。代理没开时面板照样能打开,
会继续显示上次缓存的数据并标注「拉取失败」——把代理打开后点「刷新」即可恢复。
商品信息导入(想要 SKU 就靠它)
TikTok 广告接口只给商品 ID(SPU),SKU 编码和商品名只在卖家中心里。所以第一次用建议先做这一步, 做完广告组下钻的「SKU」列、SKU 汇总、商品 × 广告合并才有数据。
卖家中心:商品 → 批量操作 → 编辑商品 → 选择商品 → 模板选「全部信息」→ 生成模板 → 已下载,拿到 xlsx
面板 → 左侧 「商品信息」 → 选店铺区域 → 选文件 → 导入
回「广告组」点任意一行下钻 → 看 SKU 汇总和素材表的 SKU 列
完整图文步骤(含 4 张截图):docs/PRODUCT-IMPORT.md
没导入也能用,只是 SKU 列会显示
-;上新/改 SKU 后重新导出导入一次即可。
一、概况:重点功能与它们解决的问题
功能 | 解决什么问题 | 一句话怎么用 |
模块化盯盘 | 登后台翻三层菜单才能看到数据;想知道「现在这个组/这条素材跑得怎么样」要来回点 | 点「+ 添加盯盘模块」选账户/组/素材 → 一张卡一个对象,KPI + 小时曲线,自动刷新(默认 60 秒,面板里可改成 15/30 秒) |
日期对比 + 累计对比 | 只知道今天消耗多少,判断不出「比昨天好还是差」;更不知道「到下午 4 点为止累计出了多少单」 | 卡片上「📅 日期对比」选昨天/前天/7 天前,双曲线叠加;鼠标悬浮显示到该小时为止的累计订单 / 累计消耗 / 累计 ROI(均值) |
广告组下钻(SKU + 素材) | 只知道某个组烧钱,不知道是哪个 SKU、哪条素材在花;素材超 1000 条时后台翻页翻不动 | 广告组列表点任意一行 → 左边 SKU 汇总(消耗/占比/订单/ROI),右边素材表(状态/作品 ID/达人/SKU/CTR),可排序、按状态筛选、搜作品 ID |
数据导出 | 每天手工从后台导 Excel、格式还不统一 | 选日期区间 → 一次生成每天一个 xlsx(商品明细 / 素材明细 / SKU 销量 / 说明),网页直接下载 |
商品信息导入 | 广告接口只有商品 ID(SPU),看不到 SKU 编码和商品名 | 导入卖家中心导出的商品表,SKU 列/商品×广告合并立刻有数据(见上一节) |
二、三种接入方式(挑一个)
方式 1:DeepSeek Harness 插件(完整能力,含面板)
1) 把本仓库放进 DSH 插件目录:<DSH_HOME>/profiles/<profile>/plugins/dsh-plugin-tiktok-ads
2) profile 的 package.json dependencies 加 "dsh-plugin-tiktok-ads": "link:./plugins/dsh-plugin-tiktok-ads"
3) dsh.profile.bundles 里加入 "dsh-plugin-tiktok-ads"注册 6 个工具:tiktok_ads_status / connect / disconnect / tools / call / panel。
插件会自动启动本地监控面板(默认 http://127.0.0.1:8790)。
方式 2:命令行(任何能跑命令的 AI 都能用)
git clone https://github.com/penyy8540-bit/tiktok-ads-agent-kit.git && cd tiktok-ads-agent-kit
node tools/ads-cli.mjs status # 是否已授权
node tools/ads-cli.mjs login # 生成授权链接并打开浏览器
node tools/ads-cli.mjs accounts # 已授权账户 + GMV Max 店铺
node tools/ads-cli.mjs report --days 7 # 近 7 天汇总(JSON)
node tools/ads-cli.mjs creatives --days 1 --pretty
node tools/ads-cli.mjs export --start 2026-10-28 --end 2026-10-28 --out ./reports
node tools/ads-cli.mjs panel --port 8795 # 可视化面板(不依赖 DSH)所有命令默认输出 JSON,方便模型直接解析。
方式 3:MCP Server(Claude Desktop / Cursor / 任意 MCP 客户端)
{
"mcpServers": {
"tiktok-ads": {
"command": "node",
"args": ["D:/path/to/dsh-plugin-tiktok-ads/tools/mcp-server.mjs"],
"env": { "TIKTOK_ADS_PROXY": "auto" }
}
}
}暴露的工具:tiktok_status、tiktok_login、tiktok_accounts、tiktok_report、
tiktok_campaigns、tiktok_creatives、tiktok_tools_search、tiktok_call、tiktok_export。
更细的 AI 使用说明(提示词模板、字段解释)见 docs/AI-USAGE.md。 商品表(SKU / 商品名)怎么从卖家中心导出并导入见 docs/PRODUCT-IMPORT.md。
三、快速开始(5 分钟)
# 1. 准备:Node.js 22+
node -v
# 2. 授权(会打开浏览器登录 TikTok for Business)
node tools/ads-cli.mjs login
# 3. 验证
node tools/ads-cli.mjs status
node tools/ads-cli.mjs accounts
# 4. 拉数据
node tools/ads-cli.mjs report --days 7 --pretty授权令牌保存在 ~/.dsh/plugin-data/tiktok-ads/auth.json(权限 0600,从不打印、不写日志、不返回给模型)。
访问令牌有效期约 24 小时,过期自动用 refresh token 续期。
国内网络 / 代理
默认 proxy: auto:先读 HTTPS_PROXY,读不到再读 Windows 系统代理。
也可以显式指定:
TIKTOK_ADS_PROXY=http://127.0.0.1:7890 node tools/ads-cli.mjs status四、常用数据口径(重要)
概念 | 说明 |
GMV Max 报表工具 |
|
广告组维度 |
|
商品维度 |
|
素材维度 |
|
小时数据 | 只有账户 / 广告组级有 |
作品 ID | 素材报表里的 |
时区 | 报表小时口径 = 广告账户时区,面板支持按时区换算展示 |
五、可视化面板
node tools/ads-cli.mjs panel --port 8795 # 或 node tools/panel-preview.mjs --port 8795能力:
盯盘:一个对象一张卡,KPI(可点选 2 个做双轴)+ 小时曲线 + 每卡独立时区 + 备注 + 整日对比(今日 vs 昨天/指定日,双曲线 + 涨跌幅)
广告组:广告组 → SKU 占比 → 素材下钻(状态筛选、排序、作品 ID 搜索、达人昵称)
数据导出:选日期区间导出与桌面版同格式的 xlsx,可直接在网页下载
商品信息:上传卖家中心导出的商品表,合并商品 × 广告数据(SKU 编码/商品名来自这份表)→ 见上文「商品信息导入」与 docs/PRODUCT-IMPORT.md
面板只监听
127.0.0.1,仅本机可访问。
六、Excel 导出
# 单天
node tools/daily-report.mjs --date 2026-10-28 --flat --out ./reports
# 日期区间(每天一个文件)
node tools/ads-cli.mjs export --start 2026-10-20 --end 2026-10-28 --out ./reports每个 xlsx 含:商品明细 / 素材明细 / SKU 销量 / 说明 四个 sheet。
导出需要 Python + openpyxl(仅导出功能需要;只跑 CLI 报表不需要 Python)。
可用 PYTHON_PATH 指定解释器。
七、配置
优先级:环境变量 > 插件 config > 默认值
环境变量 | 作用 | 默认 |
| 数据目录(令牌、缓存、看板) |
|
|
|
|
|
|
|
| 自定义 MCP 端点 | TikTok 官方 layer 端点 |
DSH 插件方式下,这些字段写在 cordis.patch.yml 的 config 里
(mode / expose / proxy / callbackPort / dashboardPort / monitorIntervalMinutes / rules 等)。
八、安全与隐私
令牌只存本地
auth.json(0600),不进入日志、不进入工具返回值、不进入面板 HTML面板只绑定
127.0.0.1代码零第三方依赖,除用户配置的代理外只访问 TikTok 官方域名
.gitignore已排除node_modules/、__pycache__/、reports/、本地授权文件
九、项目结构
lib/
core.js 与框架无关的核心(OAuth / MCP 会话 / callTool)——插件、CLI、MCP server、独立面板共用同一套
queries.js 常用查询(账户、广告组报表、素材报表)
index.js DSH 插件入口(注册 6 个工具 + 启动面板)
oauth.js OAuth DCR + PKCE + 本地回调
transport.js 零依赖 HTTPS / CONNECT 代理
mcp.js MCP Streamable HTTP 客户端
registry.js 工具目录检索
panel.js 面板 HTTP 服务端 + 数据 provider
dashboard.js 面板前端(手写 SVG 图表)
board.js 盯盘看板(模块、采样、告警)
monitor.js 定时扫描 + 飞书推送
products.js 卖家中心商品表导入
tools/
ads-cli.mjs 命令行入口
mcp-server.mjs stdio MCP server
panel-preview.mjs 独立运行面板
daily-report.mjs Excel 报表生成
dev/ 调试脚本(CDP 截图、页面体检等,不参与发布)
parse-product-export.py 商品表解析
test/ 35 个单元测试npm test # 35 个测试
node tools/ads-cli.mjs status # 冒烟检查十、English quick start
What it is — An agent-friendly TikTok Ads toolkit: OAuth (DCR + PKCE) → official TikTok Ads MCP → campaign / creative / SKU reports → local dashboard → Excel export. Zero runtime dependencies, Node ≥ 22.
Three entry points
node tools/ads-cli.mjs login # OAuth; token stored locally at 0600
node tools/ads-cli.mjs report --days 7 # JSON output
node tools/mcp-server.mjs # stdio MCP server for Claude/Cursor/etc.Exposed MCP tools: tiktok_status, tiktok_login, tiktok_accounts, tiktok_report,
tiktok_campaigns, tiktok_creatives, tiktok_tools_search, tiktok_call, tiktok_export.
Key API quirks (they cost hours to discover):
Reports use
gmv_max_report_get, not the genericreport_get.item_group_idreports requirefiltering.campaign_ids.item_id(creative) reports require bothcampaign_idsanditem_group_ids.Hourly granularity exists only for advertiser / campaign level — not for creatives.
Security — tokens never appear in logs or tool output; the dashboard binds to 127.0.0.1 only.
License
MIT © see LICENSE
本项目与 TikTok / 字节跳动无隶属关系,仅通过官方 TikTok for Business API 访问你自己有权限的广告账户。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
TikTok Ads MCP server: run TikTok campaigns, ad groups, ads and reports from AI.
Hosted TikTok ads MCP with OAuth, bounded reads, and prepare/confirm writes.
Hosted MCP server for marketing agencies: connect Google Ads, GA4, Search Console, Meta, LinkedIn and more to Claude or ChatGPT. Pull reports and make changes via OAuth login, no setup.
Meta Ads and Google Ads MCP server: 250+ tools for Claude, ChatGPT, Cursor and Codex.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for managing and analyzing Meta Ads (Facebook/Instagram) with over 80 natural-language tools for AI agents like Claude Desktop.-
- AlicenseAqualityDmaintenanceMCP server to manage Meta Ads (Facebook/Instagram) campaigns, ad sets, insights, and audiences from Claude Code using natural language.9MIT
- AlicenseBqualityDmaintenanceMCP server for Meta Ads providing 30 tools for account discovery, campaign management, targeting research, and insights. Designed with LLM-friendly outputs and productivity features like cloning and bulk operations.311MIT
- AlicenseAqualityDmaintenanceMCP Server for the Meta Marketing API. Gives Claude Desktop direct access to your ad account data — campaign performance, creative analysis, audience breakdowns, and budget pacing.10280 npm1MIT