{"id":51195024,"url":"https://github.com/davidmosiah/google-ads-intent-mcp","last_synced_at":"2026-06-27T19:05:46.993Z","repository":{"id":355831784,"uuid":"1229801180","full_name":"davidmosiah/google-ads-intent-mcp","owner":"davidmosiah","description":"Dry-run-first Google Ads search-term intent analyzer and negative-keyword MCP for agents.","archived":false,"fork":false,"pushed_at":"2026-05-29T12:53:04.000Z","size":116,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T14:18:04.134Z","etag":null,"topics":["ads-automation","agent-tools","agentic-workflows","ai-agents","claude","codex","dry-run","google-ads","google-ads-api","local-first","mcp","mcp-server","negative-keywords","ppc","pypi","python","search-terms"],"latest_commit_sha":null,"homepage":"https://github.com/davidmosiah/google-ads-intent-mcp","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidmosiah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-05T11:54:14.000Z","updated_at":"2026-05-29T12:53:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/davidmosiah/google-ads-intent-mcp","commit_stats":null,"previous_names":["davidmosiah/google-ads-intent-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/davidmosiah/google-ads-intent-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fgoogle-ads-intent-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fgoogle-ads-intent-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fgoogle-ads-intent-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fgoogle-ads-intent-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidmosiah","download_url":"https://codeload.github.com/davidmosiah/google-ads-intent-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidmosiah%2Fgoogle-ads-intent-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34864491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ads-automation","agent-tools","agentic-workflows","ai-agents","claude","codex","dry-run","google-ads","google-ads-api","local-first","mcp","mcp-server","negative-keywords","ppc","pypi","python","search-terms"],"created_at":"2026-06-27T19:05:46.775Z","updated_at":"2026-06-27T19:05:46.988Z","avatar_url":"https://github.com/davidmosiah.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- delx header v2 --\u003e\n\u003ch1 align=\"center\"\u003eGoogle Ads Intent MCP\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"Google Ads Intent MCP\" width=\"85%\" /\u003e\n\u003c/div\u003e\n\n\u003ch3 align=\"center\"\u003e\n  Dry-run-first Google Ads search-term intent analyzer + negative-keyword MCP for agents.\u003cbr\u003eLook at search terms safely before spending budget.\n\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/google-ads-intent-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/google-ads-intent-mcp?style=for-the-badge\u0026labelColor=0F172A\u0026color=10B981\u0026logo=npm\u0026logoColor=white\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/google-ads-intent-mcp\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/google-ads-intent-mcp?style=for-the-badge\u0026labelColor=0F172A\u0026color=0EA5A3\u0026logo=npm\u0026logoColor=white\" alt=\"npm downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge\u0026labelColor=0F172A\" alt=\"License MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge\u0026labelColor=0F172A\" alt=\"Built for MCP\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/davidmosiah/google-ads-intent-mcp/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/davidmosiah/google-ads-intent-mcp?style=for-the-badge\u0026labelColor=0F172A\u0026color=FBBF24\u0026logo=github\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/davidmosiah/google-ads-intent-mcp/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/davidmosiah/google-ads-intent-mcp/actions/workflows/ci.yml/badge.svg\" alt=\"CI status\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/davidmosiah\"\u003e\u003cimg src=\"https://img.shields.io/badge/PART_OF-Delx_Agent_Stack-0EA5A3?style=for-the-badge\u0026labelColor=0F172A\" alt=\"Part of the Delx agent stack\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/davidmosiah/google-ads-intent-mcp\"\u003e\u003cimg src=\"https://img.shields.io/badge/CATEGORY-Reach-4285F4?style=for-the-badge\u0026labelColor=0F172A\" alt=\"Category\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003e ⭐ **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.\u003cbr\u003e\n\u003e 🧱 Part of the [Delx agent stack](https://github.com/davidmosiah) \u0026mdash; 15 open-source MCP servers across **body, reach and coordination**.\n\n---\n\n\u003c!-- /delx header v2 --\u003e\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## 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 \u0026 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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmosiah%2Fgoogle-ads-intent-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidmosiah%2Fgoogle-ads-intent-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidmosiah%2Fgoogle-ads-intent-mcp/lists"}