Google Ads Intent MCP
This server is a dry-run-first Google Ads search-term intent analyzer and negative-keyword planner. It lets agents classify search terms and build exclusion plans before making live account changes.
google_ads_agent_manifest— retrieve installation and runtime guidance for agent clients (e.g., Codex, Claude, Cursor).google_ads_connection_status— check CSV/API readiness without credentials.google_ads_privacy_audit— run a privacy/safety audit of dry-run, account access, and export boundaries.google_ads_classify_search_term— classify a single search term aswaste,buyer,research, orcompetitor, with optional LLM refinement.google_ads_analyze_search_terms— batch-analyze search terms (e.g., from CSV export) to categorize intent and protect converting queries.google_ads_build_negative_plan— create a dry-run negative keyword plan with configurable campaign level and match type, without applying live changes.
All analysis is local/CSV-based and dry-run, with buyer/conversion terms explicitly protected from automatic exclusion.
Analyzes Google Ads search terms for intent classification, enabling dry-run negative keyword planning and waste spend reduction without affecting live campaigns.
⭐ 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.
Related MCP server: mcp-gads
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_statusandprivacy_auditbefore action toolskeep live mutation out of v0.1
Install
pipx install google-ads-intent-mcpWith 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.csvIntent 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:
# 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.csvTo 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
google-ads-intent-mcpHermes-style config:
mcp_servers:
google_ads_intent:
command: google-ads-intent-mcp
args: []
sampling:
enabled: falseRecommended first calls:
google_ads_connection_statusgoogle_ads_privacy_auditgoogle_ads_analyze_search_termsgoogle_ads_build_negative_plan
Agent Surfaces
Tool | Purpose |
| Install/runtime guidance for agent clients |
| CSV/API readiness without credentials |
| Dry-run, account and export boundaries |
| Single-query intent classification |
| Batch CSV-style analysis |
| 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.CSV Format
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📧 Contact & Support
📨 support@delx.ai — general questions, integration help, partnerships
🐛 Bug reports / feature requests — GitHub Issues
🐦 Updates — @delx369 on X
🌐 Site — wellness.delx.ai
Available Tools
6 toolsgoogle_ads_agent_manifestD
Inputs: client.
google_ads_analyze_search_termsD
Inputs: rows (required), llm.
google_ads_build_negative_planD
Inputs: rows (required), llm, level, match_type.
google_ads_classify_search_termD
Inputs: term (required), llm.
google_ads_connection_statusD
Inputs: no named parameters.
google_ads_privacy_auditD
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Tool names suggest distinct purposes: analyzing search terms, classifying a single term, building negative plans, checking status, and auditing privacy. Potential confusion between 'analyze_search_terms' and 'classify_search_term' is mitigated by singular/plural distinction, but 'agent_manifest' is somewhat vague.
All tools share the 'google_ads_' prefix and use snake_case. However, the pattern after the prefix varies: some use verb_noun (analyze_search_terms, classify_search_term, build_negative_plan) while others use noun (connection_status, privacy_audit) or noun_noun (agent_manifest).
With 6 tools, the server is well-scoped for its apparent domain of search term analysis and negative keyword management. The count is neither too sparse nor excessive.
The tool set covers core operations for search term intent analysis and negative plan creation, plus connection and privacy checks. Missing are update/delete operations for negative plans or retrieval of existing plans, but the set is largely sufficient for its focused purpose.
Maintenance
Related MCP Connectors
Google Ads MCP: reports, search terms, negatives, budgets, campaigns. Approval on every write.
Hosted Google Ads MCP for Claude and ChatGPT. Preview every write. No developer token.
Google Ads MCP server: run Search, Display, Demand Gen and PMax campaigns from AI.
- AdCopilotDeprecatedcloud.adcopilot
Google Ads, GA4, Search Console and Tag Manager for AI assistants. Every change is proposed first.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server that lets any LLM manage Google Ads campaigns from the terminal. Supports read and write operations.-
- AlicenseNot gradedqualityBmaintenanceEnables querying and managing Google Ads campaigns, keywords, assets, and more via natural language, with support for multiple MCP clients.169 npm1MIT
- AlicenseAqualityBmaintenanceExtends the official Google Ads MCP with a safe write layer for creating paused-by-default Search campaigns and an account auditor, all running locally with no hosted dependencies.131Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server that enables safe, audited mutation of Google Ads campaigns—creating ads, ad groups, keywords, and assets or adjusting budgets and statuses—with a dry-run default and an optional guarded remove operation, plus read-only Keyword Planner ideas.222MIT