{ "markdown": "\n

Google Ads Intent MCP

\n\n
\n \"Google\n
\n\n

\n Dry-run-first Google Ads search-term intent analyzer + negative-keyword MCP for agents.
Look at search terms safely before spending budget.\n

\n\n

\n \"npm\n \"npm\n \"License\n \"Built\n

\n\n

\n \"GitHub\n \"CI\n \"Part\n \"Category\"\n

\n\n

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

\n\n> ⭐ **If this agent-first tool helps your workflow, please star the repo.** Stars make this tooling easier for other builders to discover and help Delx keep shipping open infrastructure.
\n> 🧱 Part of the [Delx agent stack](https://github.com/davidmosiah) — 15 open-source MCP servers across **body, reach and coordination**.\n\n---\n\n\n\nDry-run-first Google Ads search-term intent analyzer for agents. It helps Codex, Claude, Cursor, Hermes, OpenClaw and other MCP clients classify search terms, protect buyer intent and draft negative-keyword plans from CSV exports before any live account change.\n\nUse it when an agent needs to reduce wasted spend without accidentally excluding buyer-intent queries.\n\n## HTTP (v2 stateless)\n\nNot shipped. Optional FastMCP extra is **stdio-only** (same skip as `delx-agent-utilities`: no `/health` without extra Starlette routes). Dry-run analysis stays request-stateless over stdio.\n\n## Why It Exists\n\nGoogle Ads cleanup is risky when agents act directly on accounts. This package makes the safe path the default:\n\n- analyze exported search-term CSVs locally\n- classify waste, buyer, research and competitor intent\n- draft negative-keyword plans without applying them\n- expose `manifest`, `connection_status` and `privacy_audit` before action tools\n- keep live mutation out of v0.1\n\n## Install\n\n```bash\npipx install google-ads-intent-mcp\n```\n\nWith MCP support:\n\n```bash\npipx install \"google-ads-intent-mcp[mcp]\"\n```\n\nPublished on PyPI: [`google-ads-intent-mcp`](https://pypi.org/project/google-ads-intent-mcp/). Release automation uses PyPI Trusted Publishing, so GitHub Actions can publish future versions without long-lived PyPI tokens. See [docs/pypi-publishing.md](docs/pypi-publishing.md).\n\n## CLI\n\n```bash\ngoogle-ads-intent manifest --client codex\ngoogle-ads-intent doctor\ngoogle-ads-intent privacy-audit\ngoogle-ads-intent classify \"free robux generator no verification\"\ngoogle-ads-intent analyze-csv --csv examples/search_terms.csv\ngoogle-ads-intent plan-negatives --csv examples/search_terms.csv\n```\n\n### Intent classification\n\nThe classifier is a deterministic, dependency-free heuristic with broad,\ncross-vertical signal coverage (ecommerce, B2B/SaaS, local services, health,\nfinance, education and more) — not just gaming traffic. It sorts each search\nterm into `waste`, `buyer`, `research` or `competitor` intent and protects\nconverting queries from being flagged as negatives.\n\nAn **optional** LLM/embeddings-backed refinement path is available and is\n**off by default**. It requires no extra dependencies or API keys for normal\nuse, and always falls back to the heuristic when no backend is configured:\n\n```bash\n# Opt in via flag (falls back to the heuristic if nothing is configured)\ngoogle-ads-intent --llm classify \"crm software pricing\"\n\n# Or via environment variable\nGOOGLE_ADS_INTENT_LLM=1 google-ads-intent analyze-csv --csv export.csv\n```\n\nTo actually call a backend, set `OPENAI_API_KEY` (and optionally\n`GOOGLE_ADS_INTENT_LLM_MODEL`, default `gpt-4o-mini`) and install the `openai`\npackage. Without those, `--llm` is a no-op that keeps the heuristic result.\nEach classification reports which path produced it via a `source`\n(`heuristic` or `llm`) field.\n\n## MCP\n\n```bash\ngoogle-ads-intent-mcp\n```\n\nHermes-style config:\n\n```yaml\nmcp_servers:\n google_ads_intent:\n command: google-ads-intent-mcp\n args: []\n sampling:\n enabled: false\n```\n\nRecommended first calls:\n\n1. `google_ads_connection_status`\n2. `google_ads_privacy_audit`\n3. `google_ads_analyze_search_terms`\n4. `google_ads_build_negative_plan`\n\n## Agent Surfaces\n\n| Tool | Purpose |\n|---|---|\n| `google_ads_agent_manifest` | Install/runtime guidance for agent clients |\n| `google_ads_connection_status` | CSV/API readiness without credentials |\n| `google_ads_privacy_audit` | Dry-run, account and export boundaries |\n| `google_ads_classify_search_term` | Single-query intent classification |\n| `google_ads_analyze_search_terms` | Batch CSV-style analysis |\n| `google_ads_build_negative_plan` | Dry-run negative keyword plan |\n\n## Copy-Paste Agent Prompt\n\n```text\nUse google-ads-intent-mcp. First call google_ads_connection_status and google_ads_privacy_audit.\nAnalyze the search terms, protect buyer/conversion queries, and return a dry-run negative plan only.\n```\n\n## CSV Format\n\nThe parser accepts common exported columns such as:\n\n- `search_term`, `Search term`, `Query`\n- `cost`, `Cost`, `cost_micros`\n- `clicks`, `Clicks`\n- `conversions`, `Conversions`, `Conv.`\n- `impressions`, `Impr.`, `Impressions`\n\n## Safety Model\n\n- CSV analysis is local.\n- Negative plans are dry-run only.\n- Buyer/conversion terms are protected from automatic exclusion.\n- OAuth tokens, developer tokens and account identifiers should stay in local environment/config files.\n\n## Development\n\n```bash\npython3 -m venv .venv\n. .venv/bin/activate\npip install -e \".[dev]\"\npytest\npython -m compileall -q src\n```\n\n---\n\n## 📧 Contact & Support\n\n- 📨 **support@delx.ai** — general questions, integration help, partnerships\n- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/davidmosiah/google-ads-intent-mcp/issues)\n- 🐦 **Updates** — [@delx369](https://x.com/delx369) on X\n- 🌐 **Site** — [wellness.delx.ai](https://wellness.delx.ai)\n", "bytes": 7385, "sha": "cc3c2a509c9ba613f2c2337beeea4b7fd3286d1c911abacd0dc4150f12771d34", "repo_slug": "davidmosiah/google-ads-intent-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_google_ads_intent__2d0ae5ce/readme" }