mcpField
M
meta-ads-control

meta-ads-control

github.com/tristanmanchester营销与增长362 次安装7 周前更新
代码仓库

关于 meta-ads-control

meta-ads-control 是用于 Meta Marketing API 操作的技能，配有输出结构化 JSON 的脚本，覆盖账户诊断、投放报告、广告管理和定向搜索。涉及花费或投放变更时，流程要求预览、取得明确批准并在写入后验证。

主要功能

  1. 01以结构化 JSON 执行 API 操作
  2. 02读取账户、广告系列及广告组
  3. 03生成同步或异步 Insights 报告
  4. 04搜索定向条件并上传素材
  5. 05支持批处理、分页和干运行

适用场景

  1. 01检查广告账户状态与投放对象
  2. 02汇总指定日期范围的投放表现
  3. 03经批准后暂停或调整广告
  4. 04创建广告结构并上传本地素材

安装

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

$npx skills add https://github.com/tristanmanchester/agent-skills --skill meta-ads-control

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

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

LICENSE.txt
assets/
ad-create.json
adcreative-link.json
adset-create.json
batch-read-example.json
budget-update-example.json
campaign-create.json
insights-overview.json
targeting-example.json
evals/
evals.json
references/
API-GUIDE.md
FIELDS.md
OPENCLAW.md
TROUBLESHOOTING.md
WORKFLOWS.md
scripts/
meta_ads.py

详细介绍

Meta Ads 控制

使用此技能执行 Meta Marketing API 相关工作。优先使用随附脚本，因为它能提供结构化 JSON 输出、试运行保护、重试、分页、批处理、异步 Insights 任务、定向搜索和素材上传。

操作花费或投放之前

  1. 确认范围。 
    python3 scripts/meta_ads.py accounts
python3 scripts/meta_ads.py account
  2. 确认目标广告账户、币种、时区以及可写对象。
  3. 对于任何可能产生费用、更改投放或改变追踪的更改：
    • 制定简短计划，
    • 运行 --dry-run，
    • 展示要更改的确切对象和字段，
    • 等待用户明确批准，
    • 然后使用 --confirm 重新运行。
  4. 除非用户明确要求立即上线，否则新建的广告系列、广告组和广告默认设为 PAUSED。
  5. 任何写入操作之后，都要使用 get、list 或 request GET 进行写后读取验证。

身份验证与环境

脚本读取以下变量：

  • META_ACCESS_TOKEN — 实时 API 调用必需
  • META_AD_ACCOUNT_ID — 可选的默认账户，可带或不带 act_
  • META_API_VERSION — 默认为 v25.0
  • META_GRAPH_BASE — 默认为 https://graph.facebook.com

如果缺少 META_ACCESS_TOKEN，请先协助用户完成设置，不要猜测或伪造 API 响应。

OpenClaw 用户可以通过技能配置注入这些值。请参阅 OpenClaw 说明。

按任务快速开始

1) 审计或诊断账户

先从能够回答问题的最小读取操作开始。

python3 scripts/meta_ads.py account --fields id,name,account_status,currency,timezone_name,amount_spent,spend_cap
python3 scripts/meta_ads.py list campaigns --fields id,name,objective,status,effective_status,daily_budget,lifetime_budget
python3 scripts/meta_ads.py list adsets --fields id,name,campaign_id,status,effective_status,daily_budget,lifetime_budget,optimization_goal,bid_strategy
python3 scripts/meta_ads.py list ads --fields id,name,adset_id,campaign_id,status,effective_status,creative

需要一次执行多项小型读取操作时，使用 batch。首先使用最少的字段集。

2) 效果报告

使用 insights。从较小的级别和日期范围开始。对于较大的时间范围、较多的字段或细分维度，请使用 --async。

python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d
python3 scripts/meta_ads.py insights act_123 --level ad --fields ad_id,ad_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas --date-preset last_30d --async --fetch-all

如果用户要求查看转化或 ROAS，请包含 actions 和 action_values。如果用户要求查看人口统计或版位细分，请使用 --breakdowns。如果用户要求按操作类型细分，请包含 actions 并使用 --action-breakdowns。

3) 暂停、恢复或归档对象

单个对象的更改优先使用 set-status。

python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --dry-run
python3 scripts/meta_ads.py set-status 120000000000000 PAUSED --confirm

批量操作时，创建 JSON 批处理文件，并在获得批准后使用 batch。

4) 创建或更新广告系列结构

按以下顺序创建：

  1. 广告系列
  2. 广告组
  3. 创意
  4. 广告

任何嵌套参数都使用 JSON 载荷文件。请从 assets/ 中的模板开始。

python3 scripts/meta_ads.py create campaign --params-file assets/campaign-create.json --dry-run
python3 scripts/meta_ads.py create campaign --params-file work/campaign.json --confirm

python3 scripts/meta_ads.py create adset --params-file work/adset.json --dry-run
python3 scripts/meta_ads.py create adset --params-file work/adset.json --confirm

python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --dry-run
python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --confirm

python3 scripts/meta_ads.py create ad --params-file work/ad.json --dry-run
python3 scripts/meta_ads.py create ad --params-file work/ad.json --confirm

如果素材是本地文件，请先使用 upload 上传。

5) 定向探索

切勿臆造定向 ID。请先通过定向搜索解析。

python3 scripts/meta_ads.py targeting-search --type adinterest --q "running"
python3 scripts/meta_ads.py targeting-search --type adgeolocation --q "Munich"

然后将返回的 ID 和描述信息放入广告组的 targeting 规范中。

6) 不受支持或小众的端点

使用低级别的 request 子命令。

python3 scripts/meta_ads.py request GET /act_123/reachestimate --set targeting_spec=@work/targeting.json
python3 scripts/meta_ads.py request GET /120000000000000/previews --set ad_format=DESKTOP_FEED_STANDARD

对于嵌套值，优先使用 --params-file 或 @file.json 值，而不是大量内联 --set。

脚本参考

主入口点
python3 scripts/meta_ads.py --help
最实用的子命令
  • accounts — 列出令牌可访问的广告账户
  • account — 读取默认账户或指定账户
  • list — 列出广告系列、广告组、广告、创意、受众、素材、像素等
  • get — 读取节点或节点边
  • create — 创建广告系列、广告组、广告创意、广告、自定义受众，或任何受支持的账户边
  • update — 根据 ID 更新节点
  • set-status — status 的便捷封装
  • insights — 同步或异步报告
  • targeting-search — 解析定向描述信息
  • upload — 上传到 adimages 或 advideos
  • batch — 发送 Graph 批处理请求
  • request — 用于任意 Graph 路径的底层备用入口

良好 Agent 行为规范

  • 先读取，再写入。
  • 只使用足以回答问题的最少字段。
  • 对于嵌套数据，优先使用 JSON 载荷文件。
  • 只有在用户确实需要所有页面时，才使用 --fetch-all。
  • 对于耗时较长的 Insights 任务，使用 --async。
  • 如果反复出现 613 或 80004 限流错误，请暂停；缩小范围或延长重试间隔。
  • 优先使用 PAUSED 或 ARCHIVED，而非破坏性删除操作。
  • 在相关情况下，同时以原始 API 单位和常用单位报告金额。预算通常以最小货币面额为单位。
  • 写入预算时，先确认账户币种和时区。
  • 每次修改后，都通过后续读取来验证实时状态。
  • 如果请求涉及住房、就业、信贷、社会议题、选举或政治，请在继续前查看 API guide，了解特殊类别注意事项。

示例

快速查看账户近 7 天概况
python3 scripts/meta_ads.py batch --batch-file assets/batch-read-example.json
python3 scripts/meta_ads.py insights act_123 --level campaign --date-preset last_7d --fields campaign_id,campaign_name,spend,impressions,clicks,ctr,cpc,actions,action_values,purchase_roas
安全地提高预算
  1. 检查当前广告组。
  2. 准备包含新预算的更新载荷。
  3. 进行试运行。
  4. 请求确认。
  5. 执行并验证。
python3 scripts/meta_ads.py get 120000000000000 --fields id,name,status,effective_status,daily_budget,lifetime_budget
python3 scripts/meta_ads.py update 120000000000000 --params-file work/adset-budget.json --dry-run
python3 scripts/meta_ads.py update 120000000000000 --params-file work/adset-budget.json --confirm
python3 scripts/meta_ads.py get 120000000000000 --fields id,name,daily_budget,lifetime_budget,updated_time
上传图片并创建链接广告
python3 scripts/meta_ads.py upload adimages --file creative.jpg --confirm
# Put the returned image_hash into work/adcreative.json
python3 scripts/meta_ads.py create adcreative --params-file work/adcreative.json --confirm
python3 scripts/meta_ads.py create ad --params-file work/ad.json --confirm

参考资料

评论

支持 Markdown