# Google Keyword Intelligence

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

Source code: https://github.com/stufently/google-keyword-ai-mcp
License: MIT

- 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.

## Documentation

- [Google Keyword Intelligence](https://stufently.github.io/google-keyword-ai-mcp/docs/): Google Keyword Intelligence is an open-source CLI, MCP server and agent skill for collecting, enriching and analyzing Google search-demand data from…
- [Architecture](https://stufently.github.io/google-keyword-ai-mcp/docs/architecture/): Google Keyword Intelligence has three layers around one set of domain models.
- [Google Autocomplete](https://stufently.github.io/google-keyword-ai-mcp/docs/autocomplete/): Google Keyword AI uses two Autocomplete endpoints in order:
- [Сопоставимый спрос через якорь Google Trends](https://stufently.github.io/google-keyword-ai-mcp/docs/demand/): gkai demand и MCP-инструмент rank_keyword_demand ранжируют от 2 до 50 уникальных непустых ключей на общей относительной шкале. Креды Google Ads не нужны.
- [Semantic expansion](https://stufently.github.io/google-keyword-ai-mcp/docs/expansion/): gkai expand fans one seed out through Google Autocomplete and returns normalized, deduplicated keyword candidates in the standard envelope.
- [Google Ads Keyword Planner](https://stufently.github.io/google-keyword-ai-mcp/docs/google-ads/): The Google Ads provider is optional: without the full set of credentials the other sources keep working and gkai doctor reports missing credentials.
- [MCP server](https://stufently.github.io/google-keyword-ai-mcp/docs/mcp/): Start the stdio server from the repository:
- [Research pipeline](https://stufently.github.io/google-keyword-ai-mcp/docs/pipeline/): There are three research scenarios because their useful first source differs. A new niche starts with broad Autocomplete expansion; a competitor starts…
- [Privacy and local data](https://stufently.github.io/google-keyword-ai-mcp/docs/privacy/): The tool stores local state in one SQLite database:
- [Research runs](https://stufently.github.io/google-keyword-ai-mcp/docs/runs/): A 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 analysis](https://stufently.github.io/google-keyword-ai-mcp/docs/scoring/): Keyword scores are transparent weighted averages on a 0–100 scale. The four components are independent and may be unavailable.
- [Google Search Console](https://stufently.github.io/google-keyword-ai-mcp/docs/search-console/): Search Console commands require a JSON credentials file configured as search_console_credentials_path (or GKAI_SEARCH_CONSOLE_CREDENTIALS_PATH). The file…
- [Google Trends](https://stufently.github.io/google-keyword-ai-mcp/docs/trends/): Google Trends is reached through an unofficial HTTP adapter with no third-party wrappers. An official API exists but is in closed alpha with…

### 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.

## Optional

- [Full text of all docs](https://stufently.github.io/google-keyword-ai-mcp/llms-full.txt)