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 个模板文件）

• 高级测试与评估

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

Related MCP server: konquest-meta-ads-mcp

差异化优势

• 生产环境验证 - 在 37 个以上的客户广告系列中经过实战测试，涵盖真实预算和各种边缘情况

• 非简单封装 - 包含优化引擎、安全门控、验证器和回滚机制

• 知识库集成 - 读取客户情报（ICP、品牌语调、切入点）以生成更好的广告

• 内置希腊语质量保证（可适配任何语言验证）

• 所有广告创建时均为“暂停”状态 - 未经操作员明确批准，任何内容都不会上线

• 受监督，非自主 - 操作员确认每一次写入、每一次激活、每一次预算变更

工具分类

架构

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)

工具类别

引擎特性

• 优化循环 - 基于性能信号的自动化预算调整

• 实验管理 - 具有统计显著性的 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。