Google Keyword Planner MCP

What is Google Keyword Planner MCP?

Get bounded Google Ads keyword ideas or historical keyword metrics as structured, MCP-ready Apify dataset rows. The Actor uses live Google Ads Keyword Planner 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's new

• November 2026: lower per-row prices by plan, rows without data are no longer billed, and the $0.45 lookup fee stays.
• New country shortcut, minSearchVolume and maxCompetitionIndex filters, month-over-month trend fields, and a same-month result cache with fromCache.

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

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.

The SEO data provider'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 paid request per run. A provider-confirmed, zero-cost rejection may be repaired for an explicitly rejected date range or keyword; each attempt is recorded. Unknown timeouts, network failures, and paid errors are never automatically retried.

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 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	Monthly search history for the requested period.
volumeChangeLastMonthPct, volumeChangeLast3MonthsPct, volumeChangeOverPeriodPct, average3MonthVolume, peakMonth, peakMonthVolume, trend	Trend fields computed from monthlySearches (trend is rising, falling or flat). Null when there is not enough history.
hasData, fromCache	Whether Google Ads returned a search volume (billed rows only) and whether the row came from your account's same-month cache.
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": [],
  "providerTaskId": "example-provider-task-id",
  "providerCostUsd": 0.075,
  "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

A confirmed terminal handoff writes matching OUTPUT, RUN_SUMMARY, and LAST_RUN_SUMMARY records and reads them back before exiting. If storage cannot be confirmed, the run fails without claiming delivery.

• COMPLETE: every bounded returned row was persisted.
• PARTIAL: real rows were persisted, but a source row was rejected, delivery was interrupted, the charge cap was reached, or the requested date range could not be honored.
• 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 SEO data provider credentials are missing or unusable.
• UPSTREAM_FAILED: a valid request received no usable provider response, such as malformed source data, an upstream error, or a 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 Apify platform usage included. You pay for three things, and the live Apify Pricing tab is the source of truth. The per-plan row prices below take effect on 14 November 2026; until then rows are a flat $0.005 and the lookup fee is shown on the Pricing tab:

• google-ads-request: $0.45 once per completed Google Ads lookup. It is charged after the data source returns usable data or a verified empty response, never for an unusable response, and not when the answer comes from your account's same-month result cache.
• keyword-result: a price per saved row that has a search volume, lower on higher Apify plans: Free $0.0020, Bronze $0.0018, Silver $0.0016, Gold and above $0.0014. Rows Google Ads returns without a search volume are saved for completeness and are not billed.
• Actor start: $0.00005.

Run	Free plan	Gold plan and above
10 keywords or rows	about $0.47	about $0.46
100 keywords or rows	about $0.65	about $0.59
1,000 keywords or rows	about $2.45	about $1.85

One Google Ads lookup covers up to 1,000 keywords (historical metrics) or 20 seed terms (ideas), so the request fee does not grow with the size of your list. The maximum event charge per run is the request price plus $0.00005 plus the row price times maxResults. Set a maximum cost per run in Apify and the Actor stops cleanly (PARTIAL) at that limit.

The data source cost is included in these prices. The Actor records the provider-reported attempt cost in RUN_SUMMARY.providerCostUsd (null when any paid effect is unconfirmed) and the response cost on the first returned row, while later rows carry 0, so summing a dataset never multiplies a one-request charge.

The actor checkpoints provider dispatch, request billing, and each result write. A resumed run reconciles the full dataset and named charge counts before doing work. deliveryUnsettled: true and RUN_FENCE.state: "UNSETTLED" mean a paid effect could not be confirmed; that run will not automatically repeat it. When a paid write remains in flight, countsAreFinal: false makes itemsPushed and chargedEventCounts explicitly null; observedItemsPushed and observedChargedEventCounts describe the latest bounded readback. REQUEST_STATE and DELIVERY_LEDGER retain the confirmed source and delivery state without credentials.

API and MCP prompt

curl -X POST "https://api.apify.com/v2/acts/khadinakbar~google-keyword-planner-mcp/runs" \
  -H "Authorization: Bearer $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 one google-ads-request event.
• Preserve providerTaskId, source, and checkedAt in reports so claims stay tied to their data source and date.

FAQ

What is the difference between the two operations?

keyword_ideas expands 1–20 seed terms in keywords into related keyword ideas and can be sorted with sortBy. historical_metrics returns available metrics for 1–1000 known terms you already have.

Do I need a Google Ads account or my own API key?

No. You do not pass any credentials as input, and the Actor does not access an advertiser account, create campaigns, or change bids. Credentials are used only internally and are never written to the dataset, OUTPUT, or RUN_SUMMARY.

How much does a run cost?

A completed Google Ads lookup costs $0.45, each saved row with a search volume costs $0.0020 down to $0.0014 depending on your Apify plan, and the Actor start costs $0.00005, with Apify platform usage included. A 100-keyword run is about $0.65 on the Free plan. See the table in the pricing section; the live Pricing tab is the source of truth.

Are keywords with no data billed?

No. A row without a search volume is saved with hasData: false so you can see which terms Google Ads did not measure, but it carries no row fee.

What does the result cache do?

Your Apify account keeps a small private cache of recent answers. If you repeat the same request (same keywords, place, language and options) in the same calendar month, within 14 days, the Actor returns the stored rows with fromCache: true and the original checkedAt, makes no new Google Ads lookup, and does not charge the $0.45 lookup fee. Rows are still billed at the row price. Change any input, or wait for the next month, to get fresh data.

How do I filter ideas by volume or competition?

Set minSearchVolume and/or maxCompetitionIndex. Filters are applied before maxResults and before billing, so rows that do not match are neither saved nor charged. If nothing matches the run ends VALID_EMPTY.

Which of the keyword tools should I use?

Use this Actor when you need Google Ads Keyword Planner data: live volume, CPC and top-of-page bids, 12-month history, and exact location, language and network controls. For keyword difficulty and a wider keyword-research toolkit use Keyword Metrics Explorer; for bulk volume lists see Keyword Search Volume API; for what actually ranks, use Google SERP All-in-One Scraper.

Why is searchVolume null or a requested keyword missing?

Null means the data source did not supply a value, so treat it as unavailable rather than zero demand. The source may also group near-exact variants or omit terms with no eligible data, so a missing term is unmeasured, not zero-volume.

How do I target a specific country or region?

Set a two-letter country such as US, GB, DE or IN, or set at most one of locationCode, locationName, or locationCoordinate; omit them all for worldwide targeting. 2840 is the United States. An explicit location selector wins over country. Use languageCode for the search language, which is not a country selector.

Scope and responsible use

This Actor does not impersonate Google, create or modify ad campaigns, or expose a user's credentials. It reports the SEO data provider 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
• The SEO data provider Google Ads Keywords Data overview
• The SEO data provider Google Ads Keywords For Keywords Live
• The SEO data provider 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.