mcpField
P
pp-meta-ads

pp-meta-ads

github.com/mvanhorn营销与增长2.1k112 次安装今天更新
代码仓库

关于 pp-meta-ads

pp-meta-ads 是面向营销人员和 Agent 的 Meta 广告只读命令行技能，可分析广告创意疲劳、受众重叠、学习阶段和归因差异，并支持本地数据查询。

主要功能

  1. 01创意疲劳与衰退诊断
  2. 02受众重叠分析
  3. 03学习阶段故障排查
  4. 04支出与归因核对
  5. 05广告状态盘点

适用场景

  1. 01决定哪些广告创意应更新
  2. 02检查相似受众的重叠
  3. 03找出长期处于学习阶段的广告组
  4. 04审计每日支出差异

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-meta-ads

安装后在 Claude Code 中输入/pp-meta-ads确认已加载。

详细介绍

Meta Ads — Printing Press CLI

前提条件：安装 CLI

此技能使用 meta-ads-pp-cli 二进制文件。**在调用此技能中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

  1. 通过 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin： 
    npx -y @mvanhorn/printing-press-library install meta-ads --cli-only
  2. 验证：meta-ads-pp-cli --version
  3. 确保报告的安装目录已加入将调用此技能的 Agent/运行时的 $PATH。

如果 npx 安装失败（没有 Node、处于离线状态等），请改用直接通过 Go 安装（需要 Go 1.26.6 或更高版本）。此安装方式会将程序安装到 $GOPATH/bin（默认为 $HOME/go/bin），因此请将该目录加入 $PATH：

go install github.com/mvanhorn/printing-press-library/library/marketing/meta-ads/cmd/meta-ads-pp-cli@latest

如果安装后 --version 报告“command not found”，则运行时无法在 $PATH 中找到二进制文件目录。验证成功之前，请勿继续运行此技能中的命令。

何时使用此 CLI

当你需要对 Meta 广告账户进行创意疲劳诊断、受众重叠图谱分析、学习阶段取证或归因漂移检测时，请使用此 CLI。最好配合每日同步到本地存储使用，以便即时查询趋势。此 CLI 专为只读设计，绝不会用于修改广告系列、预算或受众。

禁用场景

请勿在以下情况使用此 CLI：

  • 请勿使用此 CLI 创建、暂停、修改或删除广告系列、广告组、广告、受众或创意——它是只读的。
  • 请勿使用此 CLI 管理预算或更改竞价策略——这些操作应使用 Meta Ads Manager 或 facebook-business-sdk。
  • 请勿使用此 CLI 上传受众数据——根据客户文件创建自定义受众不在此工具的范围内。

独有功能

其他任何用于此 API 的工具都不具备这些功能。

可累积的本地状态

  • fatigue — 在可配置的时间窗口内，检测 CPM 上升、频次增加且 CTR 下降的广告。

    利用此功能判断应停投哪些广告。继续投放疲劳创意，是任何账户中最值得优先避免的浪费。

    meta-ads-pp-cli fatigue --campaign 23847265 --window 14d --agent

  • decay — 对比某个创意的首次展示 CTR 与当前 CTR，并预测失效日期。

    用于判断是否停投或刷新单个创意。变化趋势和预测的失效日期是决策的关键因素。

    meta-ads-pp-cli decay --creative-id 120208734567 --agent

  • overlap — 计算自定义受众之间的两两重叠百分比，并提供蚕食效应建议。

    当广告策略趋于成熟，但相似受众之间的 ROAS 似乎被稀释时使用。可帮助判断是否合并或排除受众。

    meta-ads-pp-cli overlap --audience 23847001 --audience 23847002 --audience 23847003 --agent

  • learning — 找出卡在算法学习阶段超过 N 天的广告组，并提示根本原因（预算过低、受众过窄、事件过少）。

    当多个广告组的 ROAS 同时骤降时使用。卡在学习阶段的广告组会消耗预算，却无法实现优化。

    meta-ads-pp-cli learning --account act_4327210487520472 --min-days 7 --agent
取证查询

  • reconcile — 按日对比 Meta 报告的账户支出与洞察数据支出总额；标记归因漂移超过阈值的日期。

    每月用于归因审计。可找出 Meta 报告与洞察数据不一致的具体日期，通常是由转化归因延迟导致。

    meta-ads-pp-cli reconcile --account act_4327210487520472 --since 30d --threshold 5 --agent

  • bottleneck — 按 ROAS 从低到高排列支出最高的广告组，并通过连接学习状态与有效状态提供“原因”列。

    每周用于判断应暂停哪些广告组。优先显示影响最大的目标。

    meta-ads-pp-cli bottleneck --account act_4327210487520472 --limit 10 --agent
账户健康状况

  • stale — 找出 N 天内展示次数为零的活跃广告。

    每季度用于检查账户健康状况。展示次数为零的活跃广告通常是配置错误，或是删除后仍残留的僵尸广告。

    meta-ads-pp-cli stale --days 90 --agent

  • inventory — 按 effective_status 对账户中的所有广告分组，找出配置状态为 'ACTIVE'、但 effective_status 为 'WITH_ISSUES' 或 'DISAPPROVED' 的广告。

    每天早上第一件事就运行。已拒登但仍处于 ACTIVE 状态的广告会产生实际支出，却无法投放。

    meta-ads-pp-cli inventory --account act_4327210487520472 --by effective_status --agent

命令参考

adcreatives — 管理广告创意

  • meta-ads-pp-cli adcreatives <adId> — 获取附加到广告的创意

ads — 广告级读取操作

  • meta-ads-pp-cli ads <adAccountId> — 列出广告账户中的广告

adsets — 广告组级读取操作

  • meta-ads-pp-cli adsets <adAccountId> — 返回广告组及其定向摘要、预算、优化目标和竞价策略。

campaigns — 广告系列级读取操作

  • meta-ads-pp-cli campaigns <adAccountId> — 返回广告系列及其状态、目标和预算元数据。

customaudiences — 管理自定义受众

  • meta-ads-pp-cli customaudiences <adAccountId> — 列出广告账户中的自定义受众

delivery-estimate — 管理投放估算

  • meta-ads-pp-cli delivery-estimate <adAccountId> — 获取覆盖人数／展示次数投放估算

insights — 成效和投放洞察（创意疲劳观测台）

  • meta-ads-pp-cli insights get-account — 返回整个广告账户的汇总洞察。
  • meta-ads-pp-cli insights get-ad — 广告级洞察，包含一段时间内的频次、CPM 和 CTR。
  • meta-ads-pp-cli insights get-ad-set — 获取广告组级洞察
  • meta-ads-pp-cli insights get-campaign — 获取广告系列级洞察

me — 管理个人信息

  • meta-ads-pp-cli me — 返回访问令牌获准访问的所有广告账户。
查找合适的命令

知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

meta-ads-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可靠匹配项——请改用 --help 或缩小查询范围。

操作示例

排查广告系列中的创意疲劳
meta-ads-pp-cli fatigue --campaign 23847265 --window 14d --agent --select ad_id,ad_name,cpm_slope,frequency_now,ctr_slope,verdict

每个广告返回一行，包含 CPM 趋势、当前频次、CTR 趋势以及停用／保留判定。只选择与疲劳相关的字段以缩小输出范围，控制 Agent 上下文的大小。

查找受众相互蚕食风险
meta-ads-pp-cli overlap --audience 23847001 --audience 23847002 --audience 23847003 --agent

返回成对受众的重叠百分比和相应建议。任何高于 30% 的重叠都可以考虑合并或排除。

找出卡在学习阶段的广告组
meta-ads-pp-cli learning --account act_4327210487520472 --min-days 7 --agent

显示 learning_stage_info 中的 LEARNING 状态持续超过 7 天的广告组。“why”列会提示预算、受众或事件数据稀疏等原因。

每日开始时汇总广告库存
meta-ads-pp-cli inventory --account act_4327210487520472 --by effective_status --agent

按 effective_status 对所有广告分组。处于 DISAPPROVED 状态但配置为 ACTIVE 的类别，是每日检查中最值得优先处理的发现。

月度支出核对
meta-ads-pp-cli reconcile --account act_4327210487520472 --since 30d --threshold 5 --agent

逐日比较 Meta 报告的账户支出与过去 30 天洞察支出总和之间的差额。标记偏差超过 5% 的日期。

身份验证设置

通过 META_ACCESS_TOKEN 环境变量使用 Meta 访问令牌进行身份验证。临时使用时，可从 Graph API Explorer 生成令牌（User Access Token，有效期 1–2 小时）；重复使用时，可使用 Business Manager System Users（无有效期）。仅授予 ads_read 权限——切勿授予 ads_management 或任何写入权限。通过 /me/adaccounts 发现令牌可访问的所有账户；无需配置账户 ID。

运行 meta-ads-pp-cli doctor 验证设置。

Agent 模式

在任意命令中添加 --agent。它会展开为：--json --compact --no-input --no-color --yes。

  • 可通过管道处理 — JSON 输出到 stdout，错误输出到 stderr

  • 可筛选 — --select 保留字段子集。点分路径可深入嵌套结构；数组会逐元素遍历。对于输出冗长的 API，这对控制上下文大小至关重要：

    meta-ads-pp-cli ads mock-value --agent --select id,name,status

  • 可预览 — --dry-run 显示请求但不发送

  • 适合离线使用 — 有本地 SQLite 存储时，同步／搜索命令可以使用该存储

  • 非交互式 — 从不提示输入，所有输入均通过标志提供

  • 只读 — 不要使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应封装

从本地存储或 API 读取数据的命令会将输出封装在来源信息中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

从 .results 解析数据，并通过 .meta.source 判断数据来自实时数据还是本地数据。只有当 stdout 是终端且未设置任何机器格式标志（--json、--csv、--compact、--quiet、--plain、--select）时，才会向 stderr 输出便于人类阅读的 N results (live) 摘要；管道或 Agent 消费者以及显式指定格式的运行会在 stdout 输出纯 JSON。

Agent 反馈

当你（或 Agent）发现这个 CLI 有不对劲的地方时，请记录下来：

meta-ads-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
meta-ads-pp-cli feedback --stdin < notes.txt
meta-ads-pp-cli feedback list --json --limit 10

条目保存在本地的 ~/.local/share/meta-ads-pp-cli/feedback.jsonl。只有在设置了 META_ADS_FEEDBACK_ENDPOINT，并且传入了 --send 或设置了 META_ADS_FEEDBACK_AUTO_SEND=true 时，才会 POST 这些条目。默认情况下，数据只保存在本地。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这才是能不断积累的部分。

输出交付

每条命令都接受 --deliver <sink>。输出除了（或取代）stdout 外，还会发送到指定的目标，因此 Agent 无需手动通过管道传递，就能转发命令结果。支持三种目标：

目标效果
stdout默认；仅写入 stdout
file:<path>将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>将输出正文 POST 到该 URL（使用 application/json，或在指定 --compact 时使用 application/x-ndjson）

遇到未知方案时，系统会拒绝请求，并返回列出受支持方案的结构化错误。Webhook 请求失败时会返回非零状态，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

配置档案是一组已保存的标志值，可在多次调用中重复使用。当定时运行的 Agent 每次都以相同配置调用同一命令时，可以使用它——这就是 HeyGen 的 “Beacon” 模式。

meta-ads-pp-cli profile save briefing --json
meta-ads-pp-cli --profile briefing ads mock-value
meta-ads-pp-cli profile list --json
meta-ads-pp-cli profile show briefing
meta-ads-pp-cli profile delete briefing --yes

显式标志的优先级始终高于配置档案值；配置档案值的优先级高于默认值。agent-context 会在 available_profiles 下列出所有可用配置档案，让 Agent 能在运行时发现它们。

退出代码

代码含义
0成功
2用法错误（参数错误）
3未找到资源
4需要身份验证
5API 错误（上游问题）
7请求频率受限（请等待后重试）
10配置错误

参数解析

解析 $ARGUMENTS：

  1. 为空、help 或 --help → 显示 meta-ads-pp-cli --help 输出
  2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参阅上文的前置要求
  3. 其他任何内容 → 直接使用（作为带有 --agent 的 CLI 命令执行）

安装 MCP 服务

  1. 安装 MCP 服务： 
    go install github.com/mvanhorn/printing-press-library/library/marketing/meta-ads/cmd/meta-ads-pp-mcp@latest
  2. 在 Claude Code 中注册： 
    claude mcp add meta-ads-pp-mcp -- meta-ads-pp-mcp
  3. 验证：claude mcp list

直接使用

  1. 检查是否已安装：which meta-ads-pp-cli 如果未找到，请提供安装选项（参阅本技能顶部的前置要求）。
  2. 根据用户查询，从上文的独特功能和命令参考中选择最合适的命令。
  3. 使用 --agent 标志执行： 
    meta-ads-pp-cli <command> [subcommand] [args] --agent
  4. 如果存在歧义，请查看子命令帮助：meta-ads-pp-cli <command> --help。

评论

支持 Markdown