Google Ads Intent MCP
Dry-run-first Google Ads search-term intent analyzer + negative-keyword MCP for agents.
Look at search terms safely before spending budget.
mcp-name: io.github.davidmosiah/google-ads-intent-mcp
⭐ 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.
🧱 Part of the Delx agent stack — 15 open-source MCP servers across body, reach and coordination.
Dry-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.
Use it when an agent needs to reduce wasted spend without accidentally excluding buyer-intent queries.
HTTP (v2 stateless)
Not 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.
Why It Exists
Google Ads cleanup is risky when agents act directly on accounts. This package makes the safe path the default:
- analyze exported search-term CSVs locally
- classify waste, buyer, research and competitor intent
- draft negative-keyword plans without applying them
- expose
manifest, connection_status and privacy_audit before action tools
- keep live mutation out of v0.1
Install
pipx install google-ads-intent-mcp
With MCP support:
pipx install "google-ads-intent-mcp[mcp]"
Published on PyPI: 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.
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
Intent classification
The classifier is a deterministic, dependency-free heuristic with broad,
cross-vertical signal coverage (ecommerce, B2B/SaaS, local services, health,
finance, education and more) — not just gaming traffic. It sorts each search
term into waste, buyer, research or competitor intent and protects
converting queries from being flagged as negatives.
An optional LLM/embeddings-backed refinement path is available and is
off by default. It requires no extra dependencies or API keys for normal
use, and always falls back to the heuristic when no backend is configured:
google-ads-intent --llm classify "crm software pricing"
GOOGLE_ADS_INTENT_LLM=1 google-ads-intent analyze-csv --csv export.csv
To actually call a backend, set OPENAI_API_KEY (and optionally
GOOGLE_ADS_INTENT_LLM_MODEL, default gpt-4o-mini) and install the openai
package. Without those, --llm is a no-op that keeps the heuristic result.
Each classification reports which path produced it via a source
(heuristic or llm) field.
MCP
Hermes-style config:
mcp_servers:
google_ads_intent:
command: google-ads-intent-mcp
args: []
sampling:
enabled: false
Recommended first calls:
google_ads_connection_statusgoogle_ads_privacy_auditgoogle_ads_analyze_search_termsgoogle_ads_build_negative_plan
Agent Surfaces
| Tool | Purpose |
|---|
google_ads_agent_manifest | Install/runtime guidance for agent clients |
google_ads_connection_status | CSV/API readiness without credentials |
google_ads_privacy_audit | Dry-run, account and export boundaries |
google_ads_classify_search_term | Single-query intent classification |
google_ads_analyze_search_terms | Batch CSV-style analysis |
google_ads_build_negative_plan | Dry-run negative keyword plan |
Copy-Paste Agent Prompt
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.
The parser accepts common exported columns such as:
search_term, Search term, Querycost, Cost, cost_microsclicks, Clicksconversions, Conversions, Conv.impressions, Impr., Impressions
Safety Model
- CSV analysis is local.
- Negative plans are dry-run only.
- Buyer/conversion terms are protected from automatic exclusion.
- OAuth tokens, developer tokens and account identifiers should stay in local environment/config files.
Development
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
pytest
python -m compileall -q src
