KonQuest Meta Ads MCP

适用于 Claude Code 的受监督 Meta 广告操作系统。您可以在此处找到高级版本：https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

开放核心模型

KonQuest Meta Ads MCP 使用开放核心模型：

公开版（本仓库）- 57 个工具，MIT 许可证：

广告系列、广告组和广告的完整 CRUD（增删改查）
多素材广告创建（视频 + 静态图片，多维度）
图片上传与检索
广告系列和广告组复制
洞察与跨账户批量分析
像素与追踪诊断（5 个工具）
目录与 DPA 支持（6 个工具，包括产品集创建/更新）
完整的定向投放工具包（6 个工具）
设置就绪检查器（42+ 项检查及修复说明）
验证流水线、命名强制执行、写入后验证
安全层级、速率限制、回滚参考
215 个自动化测试

高级捆绑包 - 增加 41 个工具：

咨询优化引擎（审核队列、学习、实验、预算控制、创意轮换）
知识库智能与文案生成（品牌语调、ICP 定向、概念选择）
希腊语质量保证（希腊字母转写检测、拼写检查）
自动化套件（诊断、批量操作、账户审计）
知识库引导（每个客户 15 个模板文件）
高级测试与评估

高级捆绑包需单独购买。公开版工具在没有它的情况下也能完全正常工作。

差异化优势

生产环境验证 - 在 37 个以上的客户广告系列中经过实战测试，涵盖真实预算和各种边缘情况
非简单封装 - 包含优化引擎、安全门控、验证器和回滚机制
知识库集成 - 读取客户情报（ICP、品牌语调、切入点）以生成更好的广告
内置希腊语质量保证（可适配任何语言验证）
所有广告创建时均为“暂停”状态 - 未经操作员明确批准，任何内容都不会上线
受监督，非自主 - 操作员确认每一次写入、每一次激活、每一次预算变更

工具分类

分类	数量	描述
production-safe	38	只读数据访问。无 API 写入，无本地状态更改。
supervised-only	29	需要操作员批准后方可执行的写入/删除操作。
advisory-only	31	生成建议、计划、文案、诊断。无 Meta API 写入。可能会写入本地文件。
总计：98 个已注册

架构

meta_ads_mcp/
  core/          # 66 tools - API read/write operations
  engine/        # 32 tools - optimization, review, learning, experiments
  validators/    # Quality gates (compliance, creative specs, tracking, structure)
  safety/        # Rate limiting, rollback, duplicate checking, file locks, tier access
  ingestion/     # Internal: video manifest management
  reporting/     # Internal: not currently active (see Non-Shipped Code)

工具类别

类别	工具数	描述
账户管理	6	令牌健康度、广告账户、主页、IG 身份、发现
广告系列	4	创建、读取、更新广告系列
广告组	4	创建、读取、更新带有定向设置的广告组
广告	4	创建、读取、更新广告
创意	3	创建、读取广告创意
洞察与分析	1	带有原型感知归一化的性能数据
像素与追踪	5	像素健康度、事件诊断、测试事件、CAPI
目录与 DPA	6	产品目录、Feed、产品集、验证
受众	1	自定义受众列表
定向投放	3	兴趣、行为和地理位置搜索
视频管理	3	上传（简单 + 可恢复）及处理状态
广告构建器	1	带有 IG 门控强制执行的多素材广告创建
文案引擎	2	基于知识库的广告文案生成与验证
命名规范	1	所有对象的强制命名架构
自动化与诊断	6	希腊语 QA、全面诊断、批量操作、账户审计
知识库与智能	2	客户知识库读取器、概念选择
优化引擎	4	优化周期、发布计划、执行包
变动走廊	2	带有验证的预算/定向变更
激活与回滚	4	状态变更及带有预检的撤销
审核队列	7	操作员审核队列、结果快照、摘要
学习层	5	策略记忆、结果评估、学习周期
实验	7	A/B 测试、预算控制、创意轮换、扩量
文案生成	2	自动文案链、基于知识库的希腊语文案

引擎特性

优化循环 - 基于性能信号的自动化预算调整
实验管理 - 具有统计显著性的 A/B 测试追踪
预算控制 - 通过可配置的每日/终身限额防止超支
创意轮换 - 疲劳度检测及自动创意刷新触发器
策略学习 - 追踪操作结果并随时间调整置信度
命名门控 - 在任何 API 写入前强制执行命名规范

安全特性

速率限制 - 尊重 Meta API 速率限制并进行退避处理
回滚 - 通过执行日志撤销最近的更改
重复检查 - 防止意外创建重复的广告系列/广告
文件锁 - 安全的并发访问知识库存储
分级访问 - 每个账户的安全层级（沙盒、标准、生产）

验证器套件

合规性验证器 - Meta 广告政策预检
创意规格验证器 - 图片/视频尺寸和格式验证
追踪验证器 - 发布前的像素和事件验证
结构验证器 - 广告系列结构一致性检查
操作验证器 - 预算、排期和定向投放合理性检查

未发布代码

存在于仓库中但不是活动工具表面的代码：

reporting/templates.py, reporting/formatter.py - 运行时不导入，无主动报告生成
evals/ - 内部评估存根，不对操作员开放
内部辅助工具 (非 MCP 工具): identity.py (IG 解析), api.py (HTTP 客户端), auth.py (令牌验证), utils.py (格式辅助), safety/ (速率限制器、回滚、去重), validators/ (预写入验证流水线)

设置

1. 安装

cd meta-ads-mcp
uv sync

2. 环境变量

将 .env.example 复制为 .env 并填入您的值：

cp .env.example .env

必需：

META_ACCESS_TOKEN - Meta Marketing API 访问令牌（推荐使用系统用户令牌）

可选：

META_APP_SECRET - 用于 appsecret_proof（生产环境推荐）
META_APP_ID - Meta 应用 ID
VAULT_PATH - 您的营销知识库目录路径（默认为 ~/marketing-vault）

3. MCP 配置

添加到您的 Claude Code MCP 配置 (.mcp.json) 中：

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": ["--directory", "/path/to/meta-ads-mcp", "run", "python", "-m", "meta_ads_mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here",
        "VAULT_PATH": "/path/to/your/marketing-vault"
      }
    }
  }
}

4. 知识库结构（可选）

如果使用知识库集成进行客户情报分析：

your-vault/
  01_CLIENTS/{client-slug}/
    00-profile.md        # Account IDs, pixel, page, IG
    02-icp-personas.md   # Target audience profiles
    04-brand-voice.md    # Tone, language, style rules
    05-messaging-house.md # Angles, value props
    08-objections.md     # Objections + bias deployment
    matrix.md            # Decision Matrix
  02_COMPETITORS/{slug}/
    landscape.md         # Competitive landscape

测试

uv run --extra dev python -m pytest tests/ -v
# Public package: 215 passed | Full (with premium): 246 passed

许可证

MIT - 参见 LICENSE。

konquest-meta-ads-mcp