Google Keyword Planner MCP

Get bounded Google Ads keyword ideas or historical keyword metrics as structured, MCP-ready Apify dataset rows. The Actor uses the current DataForSEO Google Ads Live endpoints, which are based on Google Ads data. Each returned row preserves the requested targeting, monthly volume, competition, CPC and top-of-page bid fields, monthly trend, source, provider task ID, and timestamp.

Use it when an SEO, PPC, content, or product-marketing workflow needs a reproducible keyword-research snapshot rather than browser automation of Google Keyword Planner. For an observed SERP result rather than planning metrics, use the public Google SERP All-in-One Scraper in the next step.

What this Actor does

Choose one focused operation:

• keyword_ideas expands 1–20 seed terms into related Google Ads keyword ideas.
• historical_metrics checks 1–1000 known terms and returns their available historical metrics.

Both operations accept one optional geographic selector, language, search-partner setting, adult-keyword flag, and an output cap of 1–1000 rows. keyword_ideas accepts an upstream sort order. This is deliberately a narrow metrics-and-ideas tool: it does not create campaigns, change bids, access an advertiser account, or claim first-party Search Console traffic.

How one workflow works

A B2B SaaS marketer starts with five product-language phrases. They run keyword_ideas in US English with a 200-row cap, sort by search_volume, and group the returned rows by the keyword, searchVolume, competitionIndex, and cpcUsd fields. They shortlist phrases with viable intent, then run historical_metrics on that shortlist before committing a content brief or PPC test.

Each dataset row captures its target location, language, search-network setting, checkedAt, providerTaskId, and source. That lets the marketer distinguish a real metric snapshot from a generic estimate when the research is reviewed later.

Credentials and input

Set DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD as encrypted Actor environment variables using the buyer-authorized credentials from DataForSEO API access. The credentials are used only for the HTTPS Authorization header; they are never accepted as visible input or written to datasets, OUTPUT, or RUN_SUMMARY.

DataForSEO's Google Ads Live endpoints permit up to 20 idea seeds or 1000 metric terms per request and are rate limited by the provider. The Actor makes one bounded provider request per run, so a request remains auditable and does not conceal a fan-out of provider calls.

Example: keyword ideas

{
  "operation": "keyword_ideas",
  "keywords": ["project management software", "team collaboration tool"],
  "locationCode": 2840,
  "languageCode": "en",
  "searchPartners": false,
  "includeAdultKeywords": false,
  "sortBy": "search_volume",
  "maxResults": 200
}

Example: historical metrics

{
  "operation": "historical_metrics",
  "keywords": ["project management software", "team collaboration software"],
  "locationCode": 2840,
  "languageCode": "en",
  "dateFrom": "2025-08-01",
  "dateTo": "2026-07-31",
  "maxResults": 100
}

Set at most one of locationCode, locationName, or locationCoordinate; omit all three for worldwide targeting. 2840 is the DataForSEO location code for the United States. Dates use YYYY-MM-DD; the provider determines the actual available Google Ads data period. The upstream source may group near-exact variants or omit terms with no eligible data, so interpret a missing requested term as unmeasured rather than zero-volume.

Dataset output

One dataset row represents one Google Ads keyword idea or known-term metrics response. Numeric fields can be null when Google Ads did not supply a value; null is preserved rather than turned into zero.

Field	Meaning
keyword	Keyword returned by the Google Ads data source.
searchVolume	Available average monthly search volume, or null.
competition / competitionIndex	Google Ads competition level and available 0–100 index.
cpcUsd	Available provider-reported CPC in USD.
lowTopOfPageBidUsd / highTopOfPageBidUsd	Available top-of-page bid range in USD.
monthlySearches	Provider-reported monthly history for the requested period.
closeVariants	Related near-exact variants reported for known terms.
locationCode, languageCode, searchPartners	Exact targeting supplied to the provider.
providerTaskId, providerCostUsd, source, checkedAt	Provenance and cost boundary.

Illustrative schema-valid row:

{
  "runId": "example-run-id",
  "checkedAt": "2026-08-10T12:00:00.000Z",
  "operation": "keyword_ideas",
  "keyword": "project management tool",
  "locationCode": 2840,
  "locationName": null,
  "locationCoordinate": null,
  "languageCode": "en",
  "searchPartners": false,
  "searchVolume": 1300,
  "competition": "MEDIUM",
  "competitionIndex": 42,
  "cpcUsd": 8.71,
  "lowTopOfPageBidUsd": 4.2,
  "highTopOfPageBidUsd": 13.5,
  "monthlySearches": [{ "year": 2026, "month": 7, "searchVolume": 1200 }],
  "closeVariants": [],
  "categories": [],
  "provider": "dataforseo_google_ads",
  "providerTaskId": "example-provider-task-id",
  "providerCostUsd": 0.075,
  "source": "Google Ads data via DataForSEO",
  "warnings": []
}

The keyword_metrics dataset view is for the decision fields. trend_and_provenance keeps monthly history, close variants, provider task ID, cost, source, and warnings together for audit.

Terminal outcomes

Every terminal run writes OUTPUT, RUN_SUMMARY, and LAST_RUN_SUMMARY before it exits.

• COMPLETE: every bounded returned row was persisted.
• PARTIAL: some provider rows were persisted and another row could not be written.
• VALID_EMPTY: the provider completed but returned no rows for the supplied targeting.
• INVALID_INPUT: fix the operation, keyword count/shape, location selector, language, or date range.
• CONFIG_ERROR: encrypted DataForSEO credentials are missing or unusable.
• UPSTREAM_FAILED: a valid request received no usable provider response, such as a credential rejection or rate limit.

resultsTruncated: true means the provider returned more rows than maxResults; this is an intentional output boundary. Inspect providerResultCount and the terminal outcome before summarizing results for an agent or stakeholder.

Pricing and provider usage

The Actor uses Apify Pay per event with platform usage passed through to the user. A completed google-ads-request costs $0.45 after DataForSEO returns a response, including a valid empty response. Each persisted keyword-result costs $0.005, and Actor start costs $0.00005. The maximum event charge is $0.45005 + ($0.005 × maxResults) before separate platform usage; the live Apify Pricing tab is the source of truth.

DataForSEO usage is a separate provider charge billed to the configured DataForSEO account. The Actor records the provider-reported request cost in RUN_SUMMARY.providerCostUsd and on the first returned row, while subsequent rows carry 0 so that summing a dataset never multiplies a one-request provider charge. Check the DataForSEO account for the authoritative charge.

API and MCP prompt

curl -X POST "https://api.apify.com/v2/acts/khadinakbar~google-keyword-planner-mcp/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "keyword_ideas",
    "keywords": ["project management software"],
    "locationCode": 2840,
    "languageCode": "en",
    "maxResults": 100
  }'

For an Apify MCP workflow, use this prompt card:

Run khadinakbar/google-keyword-planner-mcp with operation: keyword_ideas for these seed terms in US English. Return the top bounded dataset rows with keyword, searchVolume, competition, competitionIndex, cpcUsd, bid range, monthly trend, checkedAt, and source. Read OUTPUT first, distinguish VALID_EMPTY, PARTIAL, and UPSTREAM_FAILED, and preserve null metrics as unavailable values.

Read the completed default dataset through the Actor output or Apify dataset API, then read OUTPUT and RUN_SUMMARY from the default key-value store. Paginate a large dataset instead of assuming the first page includes every row.

Best-results guidance

• Use a precise location selector and language when the decision is market-specific; keep them unchanged across comparison runs.
• Start with a small, meaningfully different seed set. Idea expansion uses a maximum of 20 seeds because that is the current upstream boundary.
• Use historical_metrics for a preselected shortlist; it is the right operation for comparing known terms, not creating a keyword universe.
• Treat searchVolume: null as unavailable data, not a claim of no demand.
• Keep maxResults realistic. A higher cap can create more keyword-result charges and a larger dataset; every completed provider request also carries the documented $0.45 request event.
• Preserve providerTaskId, source, and checkedAt in reports so claims stay tied to their data source and date.

Scope and responsible use

This Actor does not impersonate Google, create or modify ad campaigns, or expose a user's credentials. It reports the DataForSEO response derived from Google Ads data under the requested targeting. Google Ads and Keyword Planner may vary by account, policy, target, and data freshness; use this output as a dated planning input, not as a traffic or conversion guarantee. Use credentials you are authorized to operate and comply with applicable provider terms, advertising policies, and law.

Source documentation

• Google Ads API: generate keyword ideas
• Google Ads API: generate historical metrics
• DataForSEO Google Ads Keywords Data overview
• DataForSEO Google Ads Keywords For Keywords Live
• DataForSEO Google Ads Search Volume Live

Builder's note

I built the provider request as one operation and one bounded call, then separated row normalization from runtime orchestration. That lets agents consume the same semantic fields for ideas and historical metrics, while preserving the things that change interpretation: targeting, null metrics, truncation, source, provider task ID, provider cost, and terminal outcome. It is a more reliable boundary than automating the Keyword Planner browser interface.