KonQuest Meta Ads MCP

KonQuest Meta Ads MCP

面向 Claude Code 的受监督 Meta Ads 操作系统。 高级版可在此处获取：https://farasokster.gumroad.com/l/konquest-meta-ads-mcp-premium

开源核心模式

KonQuest Meta Ads MCP 采用开源核心模式：

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

• 对广告系列、广告组和广告执行完整的 CRUD 操作
• 创建多素材广告（视频 + 静态图片，多种尺寸）
• 上传和检索图片
• 复制广告系列和广告组
• 洞察数据和跨账户批量分析
• 像素和跟踪诊断（5 个工具）
• 目录和 DPA 支持（6 个工具，包括创建/更新商品集）
• 完整的定向工具集（6 个工具）
• 设置就绪检查器（42 项以上检查，附修复说明）
• 验证流程、命名规范执行、写入后验证
• 安全等级、速率限制、回滚参考
• 215 项自动化测试

高级版套件——新增 41 个工具：

• 咨询式优化引擎（审核队列、学习、实验、预算管理器、创意轮换）
• Vault 智能分析和文案生成（品牌语气、ICP 定向、概念选择）
• 希腊语 QA（希腊式拉丁字母检测、拼写检查）
• 自动化套件（诊断、批量操作、账户审计）
• Vault 引导初始化（每个客户 15 个模板文件）
• 高级版测试和评估

高级版套件可单独购买。公开版工具无需高级版也能完整运行。

有何不同

• 经过生产环境测试，覆盖 37 个以上客户广告系列，包含真实预算和实际边缘情况
• 不只是封装层——包含优化引擎、安全关卡、验证器和回滚功能
• 集成 Vault——读取客户情报（ICP、品牌语气、营销角度），以生成更优质的广告
• 内置希腊语 QA（可适配任何语言验证）
• 所有广告均以暂停状态创建——未经运营人员明确批准，任何内容都不会上线
• 受监督，而非自主运行——运营人员需确认每一次写入、每一次启用和每一次预算变更

工具分类

分类	数量	说明
生产安全	38	只读数据访问。不执行 API 写入，不更改本地状态。
仅限受监督	29	执行前需要运营人员批准的写入/删除操作。
仅供参考	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	由 Vault 驱动的广告文案生成与验证
命名规范	1	对所有对象强制执行命名架构
自动化与诊断	6	希腊语 QA、完整诊断、批量操作、账户审计
Vault 与智能分析	2	客户 Vault 读取器、概念选择
优化引擎	4	优化周期、发布规划、执行包
变更通道	2	更改预算/定向并进行验证
启用与回滚	4	状态更改与撤销，并进行预检
审核队列	7	操作员审核队列、结果快照、摘要
学习层	5	策略记忆、结果评估、学习周期
实验	7	A/B 测试、预算调控器、创意轮播、扩量
文案生成	2	自动文案链、基于 Vault 的希腊语文案

引擎功能

• 优化循环 - 根据成效信号自动调整预算
• 实验管理 - 追踪 A/B 测试及统计显著性
• 预算调控器 - 通过可配置的每日/生命周期上限防止超支
• 创意轮播 - 检测创意疲劳，并触发自动创意更新
• 策略学习 - 追踪操作结果，并随时间调整置信度
• 命名门禁 - 在执行任何 API 写入前严格强制执行命名规范

安全功能

• 速率限制 - 遵守 Meta API 速率限制，并采用退避机制
• 回滚 - 通过执行日志撤销近期更改
• 重复项检查 - 防止意外创建重复的广告系列/广告
• 文件锁 - 确保并发访问 Vault 存储时的安全性
• 基于层级的访问控制 - 为每个账户设置安全层级（沙盒、标准、生产）

验证器套件

• 合规性验证器 - 预先检查 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 - 营销 Vault 目录路径（默认为 ~/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. Vault 结构（可选）

如果使用 Vault 集成来获取客户情报：

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。