Open source · MIT · Python 3.12+

CLI and MCP server for Google Ads Keyword Planner, Autocomplete, Trends and Search Console

Open-source CLI, MCP server and Claude skill that collects and analyzes Google search demand: Keyword Planner, Autocomplete, Trends, Search Console.

Get started Read the docs View on GitHub

What it does

Expands long-tail ideas from Google Autocomplete and researches niches and competitor-derived themes.
Optional Google Ads Keyword Planner metrics and Search Console opportunities with your own credentials.
Dry runs with provider-call estimates before the real request; saved runs can be resumed and exported.
Transparent 0–100 keyword scores, deterministic lexical clusters and Markdown reports.
MCP server with 15 tools; CLI and MCP return the same versioned response envelope.
Claude Code skill that starts with gkai doctor and requires a dry run before expensive research.

Quick start

Requires Python 3.12 or newer and uv. CI checks both the 3.12 compatibility floor and Python 3.14.

git clone https://github.com/stufently/google-keyword-ai-mcp.git
cd google-keyword-ai-mcp
uv sync
uv run gkai doctor --format json
uv run gkai research "running shoes" --language en --country US --dry-run

Review the dry-run sources and call estimates before making the real request:

uv run gkai research "running shoes" --language en --country US --save-run

Autocomplete and unofficial Trends work without account credentials. Results may still be partial when optional providers are unavailable; always read completeness, completeness_reason, warnings and data_quality.

MCP server and Claude Code

Start the stdio server with:

uv run google-keyword-ai

Add a project .mcp.json for Claude Code:

{
  "mcpServers": {
    "google-keyword-ai": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "google-keyword-ai"]
    }
  }
}

Run Claude Code from the repository so uv resolves this project. Environment variables and credential paths are inherited by the server. See the exact tool list and parity contract in docs/mcp.md.

Limitations

Autocomplete and Trends use unofficial, undocumented Google endpoints with no availability or compatibility guarantee. An official Trends API exists but is in closed alpha with application-gated access, so this project does not use it; OfficialTrendsAdapter only reserves the seam.
Google Ads and Search Console are optional and require your own credentials and access. There is no interactive OAuth flow; only credential files/values are consumed.
Google rounds search volumes and combines close keyword variants. Google Ads competition measures advertiser demand, not SEO difficulty.
Trends values are relative 0–100 interest within one response, not search volume.
Search Console BigQuery export is not implemented.
Clustering is deterministic and lexical; it does not use embeddings, SERPs or an LLM, and may group semantic synonyms poorly.

This project is not affiliated with or endorsed by Google. Google and related product names are trademarks of their respective owners.

FAQ

How do I install Google Keyword Intelligence?

It needs Python 3.12 or newer and uv. Clone the repository, run uv sync, then uv run gkai doctor --format json. Add uv sync --extra ads or --extra gsc for the optional Google Ads and Search Console clients.

Do I need Google credentials to use it?

No for Autocomplete and Trends, which work without account credentials. Google Ads requires your own developer token, customer ID and OAuth client values, and Search Console requires your own service-account or authorized-user credential file.

How do I connect it to Claude Code?

Add a project .mcp.json with a stdio server named google-keyword-ai that runs uv run google-keyword-ai, and start Claude Code from the repository so uv resolves the project.

Does competitor research show the keywords a competitor ranks for?

No. A site seed returns ideas Google Ads associates with that site. It does not reveal queries the competitor ranks for, organic positions or traffic.

Are Trends values search volumes?

No. Trends values are relative 0–100 interest within one response. Autocomplete and Trends use unofficial Google endpoints with no availability or compatibility guarantee.

Is this an official Google tool?

No. The project is not affiliated with or endorsed by Google, and it is released under the MIT license.

Documentation pages

Google Keyword IntelligenceGoogle Keyword Intelligence is an open-source CLI, MCP server and agent skill for collecting, enriching and analyzing Google search-demand data from…
ArchitectureGoogle Keyword Intelligence has three layers around one set of domain models.
Google AutocompleteGoogle Keyword AI uses two Autocomplete endpoints in order:
Сопоставимый спрос через якорь Google Trendsgkai demand и MCP-инструмент rank_keyword_demand ранжируют от 2 до 50 уникальных непустых ключей на общей относительной шкале. Креды Google Ads не нужны.
Semantic expansiongkai expand fans one seed out through Google Autocomplete and returns normalized, deduplicated keyword candidates in the standard envelope.
Google Ads Keyword PlannerThe Google Ads provider is optional: without the full set of credentials the other sources keep working and gkai doctor reports missing credentials.
MCP serverStart the stdio server from the repository:
Research pipelineThere are three research scenarios because their useful first source differs. A new niche starts with broad Autocomplete expansion; a competitor starts…
Privacy and local dataThe tool stores local state in one SQLite database:
Research runsA run stores the state of gkai research so the result can be inspected, exported or continued after a failure. The ordinary cache is not enough for this:…
Scoring, clustering, and niche analysisKeyword scores are transparent weighted averages on a 0–100 scale. The four components are independent and may be unavailable.
Google Search ConsoleSearch Console commands require a JSON credentials file configured as search_console_credentials_path (or GKAI_SEARCH_CONSOLE_CREDENTIALS_PATH). The file…
Google TrendsGoogle Trends is reached through an unofficial HTTP adapter with no third-party wrappers. An official API exists but is in closed alpha with…