adops-mcp

AdOps MCP

以 CSV 为先的 Google Ads + Meta Ads 分析与优化——可在 Claude、Cursor 和任何 MCP 客户端中使用。

从 Google Ads 或 Meta Ads Manager 导出 CSV → 导入 AdOps → 向 AI 助手询问有关广告系列的任何问题。

无需 OAuth。无需开发者令牌。无需排队等待 API 审批。你的数据保留在自己的设备上。

---

为什么以 CSV 为先？

Google Ads API 和 Meta Marketing API 功能强大，但有准入门槛：开发者令牌审批需要数天，Meta 应用审核需要数周，OAuth 流程也很脆弱。对大多数广告主而言，这些障碍始终无法跨越。

AdOps 采用了不同的方式。每个广告平台的仪表板上都有一个下载 / 导出按钮，可以生成 CSV，其中包含你关心的内容：广告系列表现、按天细分的指标、支出、转化次数、ROAS。AdOps 会读取该 CSV，并直接在 AI 助手中运行与每月 200 美元的优化套件相同的分析——异常检测、预算分配、A/B 显著性分析、预测、行业基准。

你的数据由你掌控。你无需将凭据交给第三方，也无需等待 3 周的审核。

---

功能

• 17 个 MCP 工具，涵盖完整的广告分析生命周期
• 4 个 MCP 资源，用于一目了然地查看仪表板
• CSV 导入，支持 Google Ads Editor、Google Ads 网页界面和 Meta Ads Manager——自动检测格式（美国与欧洲数字格式、CRLF 与 LF、BOM 处理）
• 统一的跨平台架构——将 Google 和 Meta 广告系列标准化为单一的 UnifiedCampaign / UnifiedMetrics 模型
• AI 驱动的建议——重新分配预算、扩大高 ROAS 广告系列的投放规模、暂停零转化广告系列
• 批量编辑 CSV 导出——将建议转换为 Google Ads Editor / Meta Ads Manager CSV，可直接粘贴到仪表板中，一键批量更新
• 统计异常检测——CPC 飙升、CTR 下跌、支出激增，并可配置灵敏度
• A/B 测试分析，附置信度评分
• 内置 9 个垂直行业的行业基准（电子商务、SaaS、B2B 等）
• 支出与转化预测（7/14/30 天）
• 演示模式——生成逼真的广告组合，在导入自己的数据前试用这些工具
• 91 项自动化测试——TypeScript 严格模式，全程使用 Zod 验证

---

快速开始

npm i adops-mcp-server

添加到你的 MCP 客户端（Claude Desktop claude_desktop_config.json、Cursor、VS Code、Windsurf）：

{
  "mcpServers": {
    "adops": {
      "command": "node",
      "args": ["path/to/node_modules/adops-mcp-server/dist/index.js"]
    }
  }
}

重启客户端。然后，在 Claude 中：

> Seed demo data so I can explore AdOps

（调用 ad_demo_seed）

或者导入真实数据：

> Import ~/Downloads/google-ads-report.csv as a Google Ads CSV

（调用 ad_csv_import，参数为 platform=google、csv_path=...）

---

从广告仪表板导出 CSV

Google Ads

1. 打开 ads.google.com → 广告系列视图 2.（可选）在工具栏中点击细分 → 天，获取每日指标
2. 点击下载（⬇）图标 → 选择 .csv 格式
3. 保存到磁盘，并将绝对路径提供给 ad_csv_import

Meta Ads Manager

1. 打开 business.facebook.com → 广告管理工具
2. 切换到广告系列标签页（不要选广告组或广告——这里需要广告系列级汇总数据） 3.（可选）选择细分 → 时间 → 天，获取每日指标
3. 点击报告 → 导出 → 广告系列效果（.csv）
4. 保存到磁盘，并将绝对路径提供给 ad_csv_import

两种导出方式开箱即用，无论是否按天细分数据。没有“天”列时，每个广告系列会得到一行汇总指标。按天细分时，会得到每日时间序列数据，从而充分支持预测和异常检测。

---

工具

工具	描述
ad_demo_seed	填充逼真的跨平台演示广告组合（8 个广告系列，30 天指标），让你在导入真实数据前试用 AdOps
ad_csv_import	导入 Google Ads 或 Meta Ads CSV 导出文件 — 其他所有工具均基于这些数据运行
ads_export_recommendations	将 budget_analyze 的建议导出为 Google Ads Editor CSV、Meta Ads Manager CSV、JSON 或 Markdown — 一次批量粘贴，即可让广告信息中心反映 AI 的计划
platform_connect	手动注册数据源连接（可替代 CSV 导入，适用于脚本化工作流）
campaign_list	列出并筛选所有已导入平台上的广告系列
campaign_create	手动添加广告系列（适用于假设规划）
campaign_update	更新本地存储中的广告系列设置（预算、状态、出价、排期）
campaign_pause_resume	批量暂停或恢复最多 50 个广告系列
ads_report	生成统一的跨平台效果报告
budget_analyze	分析预算分配并生成扩量／暂停建议
budget_reallocate	在不同平台的广告系列之间转移预算
audience_insights	按人口统计、地理位置和设备细分
creative_specs	平台专属图片、视频和文本要求参考
anomaly_detect	以可配置的灵敏度检测效果异常
ab_test_analyze	通过统计显著性检验比较两个广告系列
competitor_benchmark	将你的指标与行业平均值进行比较（9 个行业）
forecast_spend	预测未来 7／14／30 天的支出、转化次数和 ROAS

---

资源

资源	描述
ads://overview	跨平台信息中心摘要
ads://campaigns	所有有效广告系列及其关键指标
ads://budget	各平台的预算分配
ads://alerts	最近的效果异常和警告

---

统一指标架构

AdOps 会对各平台的指标进行规范化：

指标	公式	备注
CTR	clicks / impressions × 100	点击率（%）
CPC	spend / clicks	单次点击成本
CPM	spend / impressions × 1000	每千次展示成本
ROAS	conversion_value / spend	广告支出回报率
CPA	spend / conversions	单次获客成本
转化率	conversions / clicks × 100	%

CSV 列映射：

AdOps 字段	Google Ads CSV	Meta Ads CSV
spend	Cost（如果单位为 micros，则自动转换为等值美元）	Amount spent (USD/EUR/...)
impressions	Impressions	Impressions
clicks	Clicks	Link clicks
conversions	Conversions	Results（购买／潜在客户等）
conversion_value	Conv. value	Purchases conversion value
reach	—	Reach（仅限 Meta）
quality_score	Quality Score（如果存在）	—（仅限 Google）

欧洲区域格式的数字（125,50 = 125.50）和以分号分隔的 CSV 文件会自动检测。

---

配置

从网络角度看，AdOps 是无状态的 — 无需 API 密钥或 OAuth。唯一的配置是指定导入数据的持久化位置：

变量	描述	默认值
ADOPS_DATA_DIR	JSON 持久化目录	./data

其他所有行为均通过工具参数控制。

---

定价

套餐	价格	功能
免费版	$0	每天导入 1 个 CSV、演示模式、全部 17 个工具只读
专业版	€24 终身	不限导入次数、完整 CRUD、全部分析工具
代理商版	$59/mo	多账户、白标报告、优先支持

可通过 GitHub 获取（可自托管，免费），也可通过 MCPize marketplace 获取（托管服务）。

---

开发

git clone https://github.com/enzoemir1/adops-mcp.git
cd adops-mcp
npm ci
npm run build
npm test           # 91 tests across 10 suites
npm run inspect    # Open MCP Inspector

测试

共 91 项测试，涵盖：

• CSV 解析器（11 项测试）：RFC 4180 引号规则、BOM、欧洲/美国数字格式、分隔符检测
• Google Ads CSV 导入（7 项测试）：广告系列报告、按天细分、目标映射、欧洲区域设置
• Meta Ads CSV 导入（5 项测试）：Meta 专属列、从表头检测货币、目标映射、覆盖人数/频次记录
• 导出建议（8 项测试）：Google Ads Editor CSV 格式、Meta Ads Manager CSV 格式、JSON 封装、Markdown 渲染、min_delta_pct 筛选、数量限制、按类型汇总
• 存储：连接的增删改查、广告系列搜索、指标汇总、批量插入
• 分析：指标计算、效果报告、预测、基准
• 优化器：预算分析、重新分配、扩量/暂停建议
• 异常检测：CPC 激增检测、转化量下降、灵敏度、严重程度排序
• 端到端工作流：14 个真实用户场景

---

路线图

• v1.3 — 添加对 Google Ads Editor .csv.gz 和 Excel .xlsx 的支持
• v1.4 — 将 Google Ads / Meta Ads API 实时集成作为可选企业功能（BYOK — 自备开发者令牌并通过应用审核）
• v2.0 — 面向团队部署的多用户服务模式，支持 JWT 身份验证

---

专业版许可证

AdOps 以 免费模式 提供——ad_demo_seed、ad_csv_import、platform_connect、campaign_list、campaign_create、campaign_update、campaign_pause_resume、ads_report、budget_reallocate、audience_insights 和 creative_specs 均可免费使用。以下工具需要 专业版许可证：

• ads_export_recommendations — 用于 Google Ads Editor / Meta Ads Manager 的批量编辑 CSV 导出
• budget_analyze — AI 预算分配分析与操作建议
• anomaly_detect — 统计异常检测
• ab_test_analyze — 带有显著性和提升幅度的 A/B 测试 z 检验
• forecast_spend — 预测未来 7/14/30 天的支出和 ROAS
• competitor_benchmark — 行业基准对比

购买专业版许可证（€24，终身使用，支持 3 台设备）： https://automatiabcn.lemonsqueezy.com/buy/1525c929-832c-4472-a88a-58edbfa4e87b

或购买 独立开发者 MCP 套装（€69，包含全部 4 个服务）。

export LEMONSQUEEZY_LICENSE_KEY=YOUR-KEY-HERE

或在 MCP 客户端配置中：

{
  "mcpServers": {
    "adops-mcp": {
      "command": "npx",
      "args": ["-y", "adops-mcp-server"],
      "env": { "LEMONSQUEEZY_LICENSE_KEY": "YOUR-KEY-HERE" }
    }
  }
}

许可证验证结果会在本地缓存 24 小时——首次运行后即可完全离线使用。

---

许可证

MIT 许可证。详情请参阅 LICENSE。

由 Automatia BCN 构建。