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 the current SEO data provider 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

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	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": [],
  "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 platform usage passed through to the user. A verified google-ads-request costs $0.45 after the SEO data provider returns usable source data or a verified empty response. An unusable source response is not billed as a completed request. 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.

The SEO data provider usage is a separate provider charge billed to the configured SEO data provider account. The Actor records the total provider-reported attempt cost in RUN_SUMMARY.providerCostUsd (null when any paid effect is unconfirmed) and the successful response cost on the first returned row, while subsequent rows carry 0 so that summing a dataset never multiplies a one-request provider charge. Check the SEO data provider account for the authoritative 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 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 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.