Keyword research report

Expand a small seed list without turning the result into an automatic content plan. Every idea keeps its provider source, metric state, market, coverage and request cost visible.

Install and run the report

Install the CLI once, then run seo start to connect your site and Google data. After setup you can run this report yourself or ask your agent to run it.

Runafter install

Install the SEO CLI globally.

npm i -g seo

Run setup after installation.

seo start

Discover a bounded market-specific keyword shortlist.

seo reports run keyword-research --params '{"seeds":["local seo software"],"countryCode":"US","languageCode":"en"}' --json

What you get from this report

Expand a small seed list into bounded market-specific ideas while preserving the discovery method, metric state, provider coverage, cache status, and request cost.

Best for: You need candidate terms beyond the queries already visible in Search Console.
Needs: Seed keywords and discovery methods
You get: A limited candidate list with sources, seed terms, available metrics, trend evidence, and stable ordering.
Use next: Inspect live search results

What you need before you run it

This report uses A connected keyword provider, explicit seed and discovery-source pairs, the selected market, typed metrics, provider coverage, cache status, and local request cost.

Seed keywords and discovery methods

Set at most five seeds and choose ideas, related terms, suggestions, or a bounded combination.

Connected keyword provider

Returns candidate terms and available market estimates for the selected country, language, and optional location.

How the report finds the opportunity

The report uses existing search and page evidence to build a limited review list. An opportunity is a reason to inspect a page, not a promise of more traffic.

Bounds provider fanout before acquisition, normalises duplicate terms, and retains every observed seed and discovery method for each result.

Keeps zero, missing, invalid, partial, capped, and complete provider states distinct.

Labels source overlap and six-month trend comparisons as review signals rather than page or ranking recommendations.

Check the evidence behind each opportunity

Start with the query, page and date range behind each suggestion. Thin or partial evidence belongs in the review pile, not the implementation queue.

Read first	Why it matters
Result	A limited candidate list with sources, seed terms, available metrics, trend evidence, and stable ordering.
More detail	Provider, market, coverage, cache, request-cost, limit, warning, and caveat evidence for the full acquisition.
Read it with	Treat source overlap, volume, trend, and difficulty as ways to choose what to inspect next. They do not prove that two terms share intent or that the site can rank for them.

What the result cannot prove

Discovery methods use different expansion rules. Returned terms and metrics are provider evidence, not a complete market inventory, traffic forecast, or page recommendation.

Treat source overlap, volume, trend, and difficulty as ways to choose what to inspect next. They do not prove that two terms share intent or that the site can rank for them. Compare relevant candidates with Search Console evidence and validate representative programmatic templates before scaling.

Use a different report for these jobs

You plan to publish one page for every returned keyword without checking shared intent or page fit. You need exact current rankings or a scheduled rank history.

You need queries already associated with the site rather than independent market candidates.

Run query clusters for the Search Console property. It groups returned first-party query evidence and does not make a paid discovery request.

Search query clustering report

You need to decide whether several terms deserve one page, separate pages, or no new page.

Inspect current result snapshots for a short list in the same market, then compare representative ranking pages and existing site evidence. Discovery overlap and estimated metrics cannot establish shared intent or page fit.

Live SERP results report

Use the report with an agent or in code

The command above is enough for most work. These options let an agent, script or application run the same report with explicit input and structured output.

Use the report catalog when an agent, script or CI job needs predictable JSON instead of the normal terminal output. Check the current input first, then run the report with the validated parameters.

Check the current input before the agent or script runs the report.

seo reports describe keyword-research --json

Once the input is valid, run the report through the report catalog.

seo reports run keyword-research --params '{"seeds":["local seo software","local search tools"],"sources":["ideas","suggestions"],"countryCode":"US","languageCode":"en","limit":40}' --json

An MCP agent follows the same two-step flow. It inspects the current schema, fills the required fields and only then runs the report.

Ask the MCP server for the current report input.

{
  "id": "keyword-research"
}

Run the report after the agent has checked and filled the input.

{
  "id": "keyword-research",
  "params": {
    "seeds": [
      "local seo software",
      "local search tools"
    ],
    "sources": [
      "ideas",
      "suggestions"
    ],
    "countryCode": "US",
    "languageCode": "en",
    "limit": 40
  }
}

Install the package in a Node 22 project when your application needs to run the report directly. The result includes the same evidence, warnings and limits returned through the CLI and MCP server.

Add the SEO package to your project.

npm install seo

Run the report from your TypeScript application.

import { executeReport } from 'seo/mcp'

const result = await executeReport(
  'keyword-research',
  {
  "seeds": [
    "local seo software",
    "local search tools"
  ],
  "sources": [
    "ideas",
    "suggestions"
  ],
  "countryCode": "US",
  "languageCode": "en",
  "limit": 40
},
)

console.log(result)

What to do next

Review source overlap and metric states, then inspect the current results for a short list. Compare relevant terms with first-party evidence and validate representative templates before adding pages at scale.

01Inspect a current result snapshot for a short list in the same market.
02Compare relevant candidates with Search Console evidence and validate representative programmatic templates before scaling.

Inspect one bounded search snapshot with exact retained organic ranks, market context, result features, provider coverage, cache status, and request cost.

Live SERP results report

Check a limited keyword set against independent market estimates while keeping missing fields, provider coverage, cache status, and local request cost visible.

Keyword metrics report

Turn a large returned Search Console query set into reproducible groups that are easier to review for shared demand.