Keyword Research MCP

Keyword Research MCP is a lightweight local MCP server that connects an agent to real Google Ads keyword-planning data — search volume, monthly volumes, paid competition, and bid ranges — normalized into stable, typed shapes. It fetches and normalizes; it does not score, cluster, or label keywords.

Tools

• generate_keyword_ideas — discover keywords. Seed with seed_keywords (up to 20), a seed_url (one page), or a seed_site (a whole domain); seed_site cannot be combined with the others. Give a plain-text location (default United States) and language_code (default en), or explicit geo_target_resource_names. Ideas come back most-searched first; ideas below min_avg_monthly_searches (default 10) are dropped before the page is built, so total_size stays Google's pre-filter estimate. Paginate with cursor.

• resolve_geo_targets — list every plausible Google Ads location for a human-readable query when you need to pin down an exact target.

• get_keyword_historical_metrics — enrich an existing keyword list with average monthly searches, monthly volumes, paid competition, and bid ranges.

Search volume is real Google demand data. Paid Competition in Google Ads describes advertiser activity; this project does not present it as organic ranking difficulty and calculates no composite keyword score. Phrase grouping and intent classification are left to the calling agent.

Related MCP server: Google Ads MCP Server

Requirements

• Python 3.10 through 3.14

• uv

Google Ads credentials are not needed for tests. They are required when the production adapter connects to Google Ads.

Google Ads configuration

The production adapter uses google-ads==31.2.0 and explicitly selects Google Ads API v25. Configure exactly one target customer and one authentication method. Customer IDs may contain hyphens; they are normalized in memory.

For user OAuth, set:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="987-654-3210" # optional manager account
export GOOGLE_ADS_CLIENT_ID="client-id-placeholder"
export GOOGLE_ADS_CLIENT_SECRET="client-secret-placeholder"
export GOOGLE_ADS_REFRESH_TOKEN="refresh-token-placeholder"

For a service account, omit the three user-OAuth settings and set:

export GOOGLE_ADS_DEVELOPER_TOKEN="developer-token-placeholder"
export GOOGLE_ADS_CUSTOMER_ID="123-456-7890"
export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/service-account.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="ads-user@example.test" # optional

Alternatively, point GOOGLE_ADS_CONFIGURATION_FILE_PATH at a local google-ads.yaml:

developer_token: developer-token-placeholder
customer_id: "123-456-7890"
login_customer_id: "987-654-3210"
client_id: client-id-placeholder
client_secret: client-secret-placeholder
refresh_token: refresh-token-placeholder

Optional process settings are KEYWORD_RESEARCH_CACHE_CAPACITY (default 128) and KEYWORD_RESEARCH_LOG_LEVEL (default INFO). Credential files, google-ads.yaml, and .env files are ignored by Git.

Set up and run

uv sync
uv run keyword-research-mcp

The command runs over stdio, so it waits silently for an MCP client and writes protocol messages only to standard output.

Agent skill

skills/keyword-research/SKILL.md is a ready-to-use skill that drives these tools: it takes a niche to a shortlist of keywords worth planning content around, with sensible defaults meant to be refined per use case. Copy the skills/keyword-research/ directory into your agent's skills directory (for Claude Code, .claude/skills/).

Development

Run the same quality gate used in CI:

uv run ruff format --check .
uv run ruff check .
uv run pytest
uv build

pyright is configured but not part of the gate: the mcp 2.x server SDK registers tools through decorators that pyright's strict mode reports as unused, so it produces false positives here.

License

MIT