vibeads

@vibeads/mcp

通过 ChatGPT、Claude、Claude Code、Cursor 或任何 MCP 客户端与您的 Google Ads 账户对话。

专为本地服务型企业打造：涵盖 35 个类别，其中 32 个类别配有经过调优的关键词、CPC 基准和漏斗模板。

这是 VibeAds 的官方 Model Context Protocol 服务。您可以向助手提问，例如“哪些搜索词正在浪费我的预算？”或“我的账户健康评分是多少？”，并获取基于实时广告系列数据的答案。

与通用 Google Ads MCP 服务不同，它专为本地服务型企业预先调优，并将 35 条以上的诊断规则汇总为涵盖 6 个维度的单一账户健康评分（0–100）。在 Pro/Max 方案中，它还可以起草广告系列策略、应用有保护措施的优化、编辑关键词、出价和预算、添加广告组并发布；任何会产生花费的操作都需要您确认。

有两种连接方式，且两者都可使用相同的 29 个工具：

• 登录（OAuth）。 在 ChatGPT、Claude、Meta AI 或 Claude Code 中添加托管服务 https://getvibeads.com/api/mcp，并在提示时登录 VibeAds。无需密钥，也无需安装任何内容。
• API 密钥。 对于 Cursor、Cline、Windsurf 及任何无法登录的客户端：创建一个 vba_mcp_ 密钥并使用此 npm 软件包，或在请求头中将密钥发送给托管服务。

---

功能

• 🎯 **本地服务优先：**涵盖 27 个家庭服务垂直领域和 8 个专业服务／获客领域；其中 32 个类别各自拥有关键词种子、CPC 基准、受众细分和漏斗模板
• 📊 **账户健康评分（0–100）：**根据 6 个维度加权计算（跟踪、关键词、预算、创意、定向、表现）
• 🔍 **搜索词浪费检测：**找出每一笔浪费在零转化搜索词上的花费
• 💡 **诊断汇总：**来自 VibeAds 优化引擎的 35 条以上规则，按严重程度排序
• ✍️ **写入工具（Pro/Max）：**起草策略、应用优化、编辑关键词、出价和预算，并通过 VibeAds 网关发布
• 🔐 **登录或使用密钥：**支持 OAuth 登录的助手可直接登录，其他情况可使用可撤销的 API 密钥。您的 Google 登录信息绝不会发送给助手
• 🔒 **安全设计：**读取工具无法修改任何内容；写入工具在 VibeAds 安全防护机制内运行，任何会产生花费的操作都必须由您确认
• ⚡ **无需 GAQL：**用自然语言提问，获取 Markdown 格式的答案

---

支持的类别

**本地和家庭服务（27）：**水管工 · HVAC · 电工 · 屋顶维修 · 清洁 · 园林绿化 · 害虫防治 · 油漆 · 杂工 · 锁匠 · 车库门 · 家电维修 · 树木服务 · 围栏 · 门窗 · 地毯和地板 · 防水 · 高压清洗 · 空气管道和烘干机排气管清洁 · 商业清洁和保洁 · 泳池服务 · 垃圾清运 · 搬家 · 汽车维修 · 圣诞灯饰 · 牙医 · 律师

**专业服务和获客（8）：**房地产 · 保险 · 金融服务 · 教育 · 医疗保健 · 咨询 · SaaS · B2B 服务

咨询、SaaS 和 B2B 服务使用通用默认设置；您传入的其他类别也使用通用默认设置，而非经过调优的知识库。

---

连接

	登录（OAuth）	API 密钥
适用对象	ChatGPT、Claude（claude.ai 和 Claude Desktop）、Meta AI、Claude Code	Cursor、Cline、Windsurf，以及任何其他 MCP 客户端（如果愿意使用密钥，也可以用于 Claude Code）
使用方法	添加 https://getvibeads.com/api/mcp；应用会打开 VibeAds，登录后点击 允许访问	创建一个 vba_mcp_ 密钥，然后运行此软件包，或在请求标头中向托管服务发送该密钥
发布广告活动或启动已暂停的广告活动	ChatGPT、Claude 和 Meta AI：在你于聊天中确认预算后，可在你允许助手使用的每日限额内发布搜索广告活动；其他情况都会生成审批链接。Claude Code：始终生成审批链接	始终生成需在 VibeAds 中打开的审批链接
提高每日预算	ChatGPT、Claude 和 Meta AI：可在聊天中提高至多 20%；提高幅度更大时会生成审批链接。Claude Code：始终生成审批链接	始终生成审批链接
停止连接	设置，已连接的应用：断开连接	设置，MCP 服务密钥：撤销
速率限制	每小时 60 次调用，由已登录的应用共享	每个密钥每小时 60 次调用

审批链接只能在你自己的 VibeAds 登录会话中使用，因此密钥和已连接的应用都无法批准该链接。

选项 A：登录（无需密钥，无需安装）

ChatGPT、Claude 和 Meta AI

将服务地址添加为自定义连接器（Claude、Meta AI）或自定义 MCP 服务（ChatGPT），并在助手提示时登录 VibeAds：

https://getvibeads.com/api/mcp

各应用的分步说明：连接 ChatGPT、Claude 或 Meta AI。应用连接到你的账户时，VibeAds 会发送邮件通知你。

Claude Code

使用固定的回调端口添加服务，然后在 Claude Code 中打开 /mcp，选择 VibeAds 并在浏览器中登录：

claude mcp add --transport http --callback-port 31790 vibeads https://getvibeads.com/api/mcp

任何空闲端口都可以；31790 只是一个示例。请保持端口固定：VibeAds 会精确检查返回地址，因此之后使用不同端口登录会被拒绝（运行 claude mcp remove vibeads，然后重新添加）。VibeAds 的登录页面会将 Claude Code 标记为“此电脑上的应用”：只有在你刚刚从 Claude Code 发起连接时，才允许访问。

已登录的应用会列在设置，已连接的应用中，你可以在此断开连接，并设置助手可发布广告的每日预算上限。

选项 B：API 密钥

第 1 步：获取 API 密钥

登录你的 VibeAds 账户并生成 API 密钥：

→ 生成 API 密钥

密钥以 vba_mcp_ 开头，仅显示一次，且仅适用于你的账户。请为每个客户端或设备单独创建一个密钥，这样撤销一个密钥时不会影响其他密钥。

第 2 步：配置 MCP 客户端

此软件包在你的电脑上运行，并使用你的密钥将每次调用转发至 VibeAds。它始终使用 API 密钥；若要改为登录，请使用选项 A。

Claude Desktop

打开配置文件：

操作系统	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

将以下内容添加到 mcpServers 块中：

{
  "mcpServers": {
    "vibeads": {
      "command": "npx",
      "args": ["-y", "@vibeads/mcp"],
      "env": {
        "VIBEADS_API_KEY": "vba_mcp_YOUR_KEY_HERE"
      }
    }
  }
}

重新启动 Claude Desktop。你应该会在 🔨 工具菜单中看到 VibeAds 工具。（Claude Desktop 也可以通过自定义连接器登录：请参阅选项 A。）

Cursor

1. 打开 设置 → MCP
2. 点击 添加服务器
3. 配置：
   • 名称： vibeads
   • 命令： npx -y @vibeads/mcp
   • 环境变量： VIBEADS_API_KEY=vba_mcp_YOUR_KEY_HERE

Claude Code

claude mcp add vibeads -e VIBEADS_API_KEY=vba_mcp_YOUR_KEY_HERE -- npx -y @vibeads/mcp

Cline 和其他 MCP 客户端

使用上文 Claude Desktop 的相同配置。大多数 MCP 客户端都遵循相同的架构。

npx -y @vibeads/mcp --init 会打印可直接粘贴到各客户端的配置。

或：使用带密钥的托管服务

无需安装：向客户端提供托管地址，并在 x-vibeads-api-key 标头中发送密钥。在 Claude Code 中：

claude mcp add --transport http vibeads https://getvibeads.com/api/mcp --header "x-vibeads-api-key: vba_mcp_YOUR_KEY_HERE"

密钥也可用作 Authorization: Bearer vba_mcp_...。无法发送标头的客户端可以将密钥放入地址中（https://getvibeads.com/api/mcp?key=vba_mcp_...）；此时该地址就像密码一样，因此建议优先使用标头或登录。请参阅 Cursor、OpenAI Codex、Gemini CLI 和 VS Code with GitHub Copilot 的指南。

环境变量（此程序包）

只需设置一个环境变量：所有工具（读取和写入）都会通过服务端 VibeAds 网关运行，并使用你的 API 密钥。

变量	必填？	用途
VIBEADS_API_KEY	✅ 必填	你的 vba_mcp_... 密钥。这是此程序包所需的唯一凭据。
VIBEADS_SUPABASE_URL	可选	覆盖 VibeAds 后端 URL。默认为生产环境端点。

---

用法

连接后，你可以向助手提出以下问题：

📋 广告系列发现

“显示我的所有 VibeAds 广告系列”

“哪些广告系列已暂停？”

“列出最近创建的 5 个广告系列”

🔬 深入分析

“告诉我关于我在 Austin 的水管工广告系列的所有信息”

“我上周的 HVAC 广告系列表现如何？”

“广告系列 abc12345 的 CPA 是多少？”

📈 任意时段的报告

“比较我在 Austin 的水管广告系列 9 月和 8 月的情况”

“列出上个月整个账号按设备分类的支出”

“过去 90 天哪些关键词的支出最高？”

🔎 关键词研究

“有多少人在搜索 Austin, TX 的排水管清洗服务？”

“根据我在 Round Rock 和 Pflugerville 的服务页面，查找关键词创意”

🧾 审核整个 Google Ads 账号

连接 Google Ads 后即可使用，无需先导入任何内容：

“我的 Google Ads 预算浪费在哪里了？”

“审核我的 Google Ads 账号”

📊 账号健康状况

“我的 VibeAds 账号健康评分是多少？”

“哪个维度拉低了我的评分？”

“仅显示广告系列 xyz 的健康评分”

💸 搜索词分析

“哪些搜索词浪费了我的预算？”

“显示过去 30 天表现最好的 10 个关键词”

“我在零转化搜索词上浪费了多少钱？”

🩺 诊断与建议

“我应该先修复什么？”

“显示所有严重诊断”

“我的屋顶广告系列出了什么问题？”

---

可用工具

读取工具

工具	用途
list_campaigns	列出你在 VibeAds 中的广告系列（已发布、已导入和草稿），并显示状态、预算和类别。仅存在于 Google Ads 账户中的广告系列由 find_campaigns_to_import 列出
get_campaign_details	深入查看某个广告系列：指标、广告组、定位、着陆页和诊断信息
get_account_health_score	从 6 个维度评估账户健康状况，得分为 0–100，并给出等级；也可按广告系列查看
get_search_term_analysis	分析各广告系列最近一次同步的搜索字词，找出浪费的支出和表现出色的字词。这些字词涵盖同步前 7 天的数据（可配置成本阈值）
get_diagnostics	获取最新的 Agent 优化诊断信息，包括严重程度和建议的修复方式（最多 50 条）
find_campaigns_to_import	导入前，查看从 Google Ads 读取的 Google Ads 账户中的广告系列，并标明哪些已在 VibeAds 中（VibeAds 仅管理其中的广告系列）。在 0.2.15 版本中名为 list_google_ads_campaigns
get_performance_report	查看所选周期内某个广告系列或整个账户的数据（可选预设周期或指定两个日期，最多 90 天）。数据从 Google Ads 实时读取；还可按日期、设备、小时、广告组、关键字或位置细分。金额使用账户货币。VibeAds 会构建所有查询；助手只需选择周期和细分方式
audit_google_ads_account	审计一个已连接的 Google Ads 账户。数据从 Google Ads 实时读取：检查过去 30 天内最多 25 个搜索广告系列，无论它们是否已在 VibeAds 中；为账户和每个广告系列提供 0–100 的健康得分和等级，按检查项归类问题并说明如何在 Google Ads 中修复，同时列出每个广告系列花费最高且有点击但未带来转化的搜索字词。每个账户的审计结果会保留 24 小时
list_keywords	查看一个已发布广告系列的广告组、关键字和否定关键字。数据从 Google Ads 实时读取：匹配类型、状态、最高 CPC，以及 30 天的点击量、费用和转化次数
research_keywords	使用你指定的地点，根据种子关键字、网页或两者获取 Google 关键字规划师提供的关键字创意：月均搜索量、竞争程度和首页出价范围。需要 Pro/Max，消耗 2 个点数（90 天内重复查询免费）
list_google_ads_accounts	列出所有已连接的 Google Ads 账户，无论是否已启用，并显示每个客户账户所属的管理账户（MCC）
list_google_recommendations	获取 Google 针对某个账户提供的建议（即其“建议”页面），包括 Google 的效果预估，以及每项建议是否可以通过聊天应用

读取工具均为只读：无法在你的 Google Ads 账户中创建、修改、暂停或删除任何内容。它们通过 VibeAds 网关在服务器端运行，无论你是登录使用还是通过密钥使用，运行方式都相同。所有套餐均可使用读取工具，包括免费套餐；但 research_keywords 需要 Pro 或 Max。

写入工具（Pro/Max）

写入工具通过 VibeAds 网关在服务器端运行，只需登录或使用 API 密钥，无需其他配置（不需要 Supabase 或 Google 密钥）。每次调用均受速率限制；批准的优化会在之后进行效果衡量（如果指标变差，较小的改动会自动回滚）。任何会产生费用的操作都必须先经你确认：使用 API 密钥，或已登录的 Claude Code 时，你会收到一个需要在 VibeAds 中打开的批准链接；ChatGPT、Claude 和 Meta AI 只会在你确认聊天中的预算后，按照你为助手设置的每日限额发布内容。

工具	用途
generate_strategy	在服务端起草完整的广告活动策略（关键词、广告文案、3 个以上广告组），包含一个用于搜索企业名称的品牌广告组；在 Max 上，还会为你指定的每个竞争对手创建一个广告组。消耗 13 个额度。仅起草：不会发布，也不会花费资金
get_strategy_status	查询策略任务：状态、阶段，以及完成后起草的广告组
apply_strategy	将已完成的预览转换为实际的广告活动草稿（广告组、关键词、定位、广告文案、附加信息）。消耗 6 个额度，图片生成每个广告组另加 3 个额度。仅为草稿：不会投放，也不会花费广告费用
list_recommendations	待处理的优化建议，每条建议都包含执行它所需的工具和确切参数（包括其会话和建议 ID）；如果没有工具可以执行该更改，则提供在 VibeAds 中批准该建议的链接
preview_ad_group	展示新广告组（关键词、三条广告、着陆页方案），供你在添加前查看。仅创建预览
add_ad_group	添加已预览的广告组。在已发布的广告活动中，该广告组会立即开始投放，费用计入该广告活动的预算
request_publish	发布包含广告组的广告活动。发布会花费真实资金，因此使用 API key 或 Claude Code 时会返回人工审批 URL；在 ChatGPT、Claude 和 Meta AI 中，你确认预算后，Search 广告活动会在你允许助手使用的每日限额内发布，否则会返回审批 URL。如果有多个 Google Ads 账号，系统会询问你要使用哪个账号，并且只会发布到该账号
import_campaigns	将 Google Ads 账号中的最多 3 个广告活动导入 VibeAds，以便其优化器和报告涵盖这些活动。不会更改 Google Ads 中的任何内容。每个广告活动消耗 1 个额度
pause_campaign	暂停 Google Ads 中正在投放的广告活动
resume_campaign	重新启动已暂停的广告活动，规则与发布相同：使用 API key 或 Claude Code 时会返回人工审批 URL
add_negative_keywords	一次向某个广告活动或一个广告组添加最多 20 个否定关键词。会跳过可能屏蔽该广告活动自身关键词的否定关键词
add_keywords	一次向一个广告组添加最多 20 个关键词，采用该广告组的默认最高 CPC
set_keyword_status	暂停关键词，或重新启用已暂停的关键词
set_max_cpc	为采用 Manual CPC 的广告活动设置广告组、关键词或关键词列表的最高 CPC。一次最多可翻倍且每次点击不超过 $50；超过此范围时会返回审批 URL
set_daily_budget	设置广告活动的每日预算。降低预算会立即生效。使用 API key 或 Claude Code 提高预算时会返回审批 URL；登录 ChatGPT、Claude 或 Meta AI 后，提高不超过 20% 的部分会立即生效
dismiss_google_recommendation	从 Google 的建议列表中移除一条建议。不会更改广告活动
check_approval	查询发布或更改审批：pending → approved → executing → executed（或 rejected / expired / failed）

每项关键词、出价、预算和重启更改都会列在 VibeAds 中该广告活动的 Optimize 标签页上，并可在此撤销。VibeAds 不会自行回滚这些更改。助手每天可对一个广告活动进行 20 次更改。

从想法到广告活动上线：

1. generate_strategy 在服务端起草策略并返回 jobId。此时 Google Ads 中还没有任何内容。
2. get_strategy_status 持续查询该任务，直到状态显示为 completed。
3. apply_strategy 将完成的预览转换为实际的广告活动草稿，并返回 campaignId。仍未上线，也不会产生任何费用。
4. request_publish 接收该 campaignId。使用 API key 或 Claude Code 时会返回审批链接。
5. 在浏览器中打开该链接，并登录 VibeAds，查看广告活动及其预算，然后点击 Approve（或 Reject）。
6. check_approval 会报告审批结果，随后报告发布任务；该任务完成后，广告活动即会上线。 步骤 1–3 只会在 VibeAds 中创建行，并消耗 VibeAds 积分（步骤 1 消耗 13；步骤 3 消耗 6 + 每个广告组 3）。使用 API 密钥时，只有在步骤 5 才会实际产生广告费用，而且这一步只能在浏览器中完成：仅凭密钥绝不可能发布，因此即使密钥泄露，也无法花费广告预算。

ChatGPT、Claude 和 Meta AI 通过登录连接后，对于每日预算在你允许助手使用的限额内的搜索广告系列，可跳过链接：除非你在 VibeAds 的「设置」→「已连接的应用」中更改或关闭限额，否则限额为每天 $100。步骤 4 中，助手会告知你每日预算，并且只有在你于聊天中确认后才会发布。广告系列上线后，VibeAds 会向你发送电子邮件。预算更高的广告系列则需要通过审批链接。

---

安全性

• 读取工具是只读的。 它们无法修改你的广告系列、Google Ads 账户或 VibeAds 设置。
• 写入工具受到保护。 每项写入操作都通过 VibeAds 网关在服务器端执行，每小时最多 60 次。获批的优化会在之后进行评估，若指标恶化，较小的更改会自动回滚。助手更改的每个关键字、出价、预算和重启操作，都会列在 VibeAds 中广告系列的「优化」选项卡上，你可以在此撤销。
• 花费预算需要你确认。 审批链接只有在你自己的 VibeAds 登录会话中才有效，因此 API 密钥和已连接的应用都无法批准操作。API 密钥或已登录的 Claude Code 都不能自行发布、重启广告系列或提高预算。
• 你的 Google 登录信息由 VibeAds 保管。 Google Ads 通过 Google 自己的登录流程连接到 VibeAds。密钥或已登录的应用只能访问 VibeAds；你的 Google 令牌绝不会传给助手或你的计算机。

登录（OAuth）

• 使用 PKCE 的 OAuth 2.1 授权码流程。VibeAds 登录页面会显示发起请求的应用及其可执行的操作，你点击 允许访问 即可。
• 除这些工具外，VibeAds 不允许已登录的应用执行任何会更改你账户的操作，也绝不会让它查看你的 Google Ads 登录信息。
• 应用连接到你的账户后，VibeAds 会向你发送电子邮件。
• 在设置 → 已连接的应用中断开任何应用的连接，该应用会立即退出登录。

API 密钥

• 密钥在存储前会使用 SHA-256 进行哈希处理。完整密钥仅在创建时显示一次。
• 可随时在设置 → MCP Server Keys中撤销。
• 按密钥记录使用情况：上次使用日期和请求次数。
• 每个密钥仅对应一个 VibeAds 用户，无法查看其他用户的数据。

为确保最高安全性，每当设备转交他人或合作结束时，请撤销并更换 API 密钥。

---

要求

• 有效的 VibeAds 账户：所有套餐（包括免费套餐）均可登录并使用密钥
• Pro 或 Max 套餐：使用写入工具所需（任何套餐均可使用读取工具）
• Google Ads 已连接到 VibeAds：查看实时数据、导入和发布所需。在 VibeAds「设置」中进行连接，或通过助手在需要时提供的链接连接
• 至少一个已发布或已导入的广告系列：诊断需要 Google Ads 中已同步的数据
• Node.js ≥ 20：仅此 npm 软件包需要（使用 npx 运行）；登录或使用托管服务无需安装任何内容

---

对比

	VibeAds MCP	GoMarble MCP	Google Ads MCP（官方）
设置时间	2 分钟	15 分钟	30 分钟
连接方式	登录 VibeAds（OAuth）或使用 API 密钥；Google Ads 在 VibeAds 内连接一次即可	Google OAuth	Google OAuth
是否需要了解 GAQL	❌	✅	✅
本地服务优化调优	✅	❌	❌
账户健康评分	✅ 6 个维度	❌	❌
预置诊断	✅ 35+ 条规则	❌	❌
多账户	✅	✅	✅
有保护措施的写入操作	✅ 任何会产生花费的操作都需要你确认	❌	❌

何时使用 VibeAds MCP： 你经营本地服务业务（或为此类业务管理广告），并希望获得预先调优的洞察，而无需学习 GAQL。

何时使用 GoMarble / Google Ads MCP： 你需要运行自定义 GAQL 查询，或处理非服务型业务的广告系列（电商、B2B SaaS 等）。

三者可以共存：根据工作流安装合适的工具即可。

---

故障排除

“API 密钥无效”或“身份验证失败”

• 确保密钥以 vba_mcp_ 开头
• 在 https://getvibeads.com/app/settings/mcp 生成新密钥
• 检查密钥是否已被撤销

“缺少 VibeAds API 密钥”（使用密钥的托管服务）

标头名称必须准确为 x-vibeads-api-key，并且密钥必须以 vba_mcp_ 开头。或者移除该标头并改为登录。

助手要求你重新登录，或提示尚未连接

应用已在 Settings、Connected apps 中断开连接，或登录状态已结束。请从助手中重新连接（ChatGPT：Settings、Plugins、VibeAds；Claude：Customize、Connectors；Claude Code：/mcp）并登录。

Claude Code：登录被拒绝

添加 Claude Code 时未设置固定回调端口，或设置了不同的端口。运行 claude mcp remove vibeads，使用 --callback-port 重新添加（参见选项 A），然后从 /mcp 登录。

“尚无优化诊断结果”

VibeAds Agent 每 12 小时生成一次诊断，前提是 Google Ads 效果数据已完成同步。如果你刚发布广告系列，首次运行最多可能需要等待一天。

“未找到搜索字词数据”

搜索字词每 6 小时同步一次。对于新广告系列，请等待 24-48 小时，以积累有意义的数据。

MCP 客户端找不到服务（npm 包）

确保已安装 Node.js 20+：node --version。Claude Desktop 和 Cursor 都会通过 shell 调用 npx，因此 Node 必须位于 PATH 中。

---

贡献

这是一个开源 MIT 软件包。欢迎在以下地址提交问题和 PR： https://github.com/vibeads/mcp/issues

---

许可证

MIT © VibeAds