Google Ads Intent Mcp

Google Ads Intent MCP

以试运行优先的 Google Ads 搜索词意图分析器 + 面向 Agent 的否定关键字 MCP。
在花费预算前，安全地查看搜索词。

mcp-name: io.github.davidmosiah/google-ads-intent-mcp

⭐ 如果这款 Agent 优先的工具能助力你的工作流，请为仓库点个星标。 星标能让其他构建者更容易发现这些工具，也有助于 Delx 持续交付开源基础设施。
🧱 属于 Delx Agent Stack — 涵盖 主体、触达和协调 的 15 个开源 MCP 服务。

---

以试运行优先的 Google Ads 搜索词意图分析器，面向 Agent。它可以帮助 Codex、Claude、Cursor、Hermes、OpenClaw 和其他 MCP 客户端，在进行任何实时账户更改前，对 CSV 导出文件中的搜索词进行分类、保护买家意图，并拟定否定关键字方案。

当 Agent 需要减少无效支出，同时避免误排除具有买家意图的搜索词时，可使用此工具。

HTTP（v2 无状态）

未发布。可选的 FastMCP 扩展仅支持 stdio（与 delx-agent-utilities 一样会跳过：没有额外的 Starlette 路由就没有 /health）。试运行分析通过 stdio 保持请求无状态。

它的用途

当 Agent 直接操作账户时，清理 Google Ads 存在风险。本包将安全路径设为默认选项：

• 在本地分析导出的搜索词 CSV 文件
• 对无效、买家、调研和竞争对手意图进行分类
• 拟定否定关键字方案，但不应用这些方案
• 在操作工具之前提供 manifest、connection_status 和 privacy_audit
• 在 v0.1 中不提供实时变更功能

安装

pipx install google-ads-intent-mcp

使用 MCP 支持：

pipx install "google-ads-intent-mcp[mcp]"

已发布至 PyPI：google-ads-intent-mcp。发布自动化使用 PyPI Trusted Publishing，因此 GitHub Actions 无需长期有效的 PyPI 令牌即可发布后续版本。请参阅 docs/pypi-publishing.md。

CLI

google-ads-intent manifest --client codex
google-ads-intent doctor
google-ads-intent privacy-audit
google-ads-intent classify "free robux generator no verification"
google-ads-intent analyze-csv --csv examples/search_terms.csv
google-ads-intent plan-negatives --csv examples/search_terms.csv

意图分类

该分类器是一种确定性的无依赖启发式方法，覆盖广泛且跨行业的信号（电子商务、B2B/SaaS、本地服务、健康、金融、教育等），而不只是游戏流量。它会将每个搜索词归类为 waste、buyer、research 或 competitor 意图，并保护能带来转化的查询，避免其被标记为否定项。

另提供一条可选的、基于 LLM/嵌入的优化路径，且默认关闭。常规使用无需额外依赖或 API 密钥；若未配置后端，则始终回退到启发式方法：

# Opt in via flag (falls back to the heuristic if nothing is configured)
google-ads-intent --llm classify "crm software pricing"

# Or via environment variable
GOOGLE_ADS_INTENT_LLM=1 google-ads-intent analyze-csv --csv export.csv

若要实际调用后端，请设置 OPENAI_API_KEY（还可选择设置 GOOGLE_ADS_INTENT_LLM_MODEL，默认值为 gpt-4o-mini），并安装 openai 包。未设置这些内容时，--llm 不会执行任何操作，仍使用启发式结果。每次分类都会通过 source（heuristic 或 llm）字段报告所用路径。

MCP

google-ads-intent-mcp

Hermes 风格配置：

mcp_servers:
  google_ads_intent:
    command: google-ads-intent-mcp
    args: []
    sampling:
      enabled: false

建议的首次调用：

1. google_ads_connection_status
2. google_ads_privacy_audit
3. google_ads_analyze_search_terms
4. google_ads_build_negative_plan

Agent 接入界面

工具	用途
google_ads_agent_manifest	为 Agent 客户端提供安装/运行时指南
google_ads_connection_status	无需凭据即可检查 CSV/API 就绪状态
google_ads_privacy_audit	试运行、账户和导出边界检查
google_ads_classify_search_term	对单个查询进行意图分类
google_ads_analyze_search_terms	批量 CSV 风格分析
google_ads_build_negative_plan	生成仅供试运行的否定关键词计划

可复制粘贴的 Agent 提示词

Use google-ads-intent-mcp. First call google_ads_connection_status and google_ads_privacy_audit.
Analyze the search terms, protect buyer/conversion queries, and return a dry-run negative plan only.

CSV 格式

解析器接受常见的导出列，例如：

• search_term、Search term、Query
• cost、Cost、cost_micros
• clicks、Clicks
• conversions、Conversions、Conv.
• impressions、Impr.、Impressions

安全模型

• CSV 分析在本地进行。
• 否定关键词计划仅供试运行。
• 买家/转化相关词不会被自动排除。
• OAuth 令牌、开发者令牌和账户标识符应保存在本地环境/配置文件中。

开发

python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
pytest
python -m compileall -q src

---

📧 联系与支持

• 📨 [email protected] — 一般问题、集成帮助、合作事宜
• 🐛 错误报告 / 功能请求 — GitHub Issues
• 🐦 动态 — X 上的 @delx369
• 🌐 网站 — wellness.delx.ai