# Keyword Steroids Gold — MCP

> Hebrew gap finder: `hl=iw gl=il` Suggest (no key) + Related + PAA + Jaccard clustering + bsearch gap scan (`region=il lang=he`) + crawl audit + GSC verify/insights + Semrush gap (BYOK) + brief + SERP features. Local-first, 1.2s throttle.

**Binary:** `keyword-steroids-gold` · **Package:** `keyword-steroids-gold` · **MCP name:** `ai.studio/keyword-steroids-gold`

> **Disclosure:** This project is an independent Gold wrapper around public Google endpoints and official APIs. No-key tools use the public Google Suggest endpoint (`https://suggestqueries.google.com/complete/search?client=firefox&q=...&hl=iw&gl=il` — no key — and `https://www.google.com/search?q=...&hl=iw&gl=il` HTML scrape for Related/PAA). GSC tools use the official Google Search Console API (`https://developers.google.com/webmasters/search-console-api` — `https://www.googleapis.com/webmasters/v3/sites/...` + `/searchAnalytics/query`) via BYOK `GSC_OAUTH_JSON` (and optional BigQuery `https://cloud.google.com/bigquery/docs` via `BIGQUERY_OAUTH_JSON`). Semrush gap uses the official Semrush API (`https://www.semrush.com/api-documentation/` — `https://api.semrush.com/?type=domain_organic...`) via BYOK `SEMRUSH_API_KEY`. We are not affiliated with Google LLC or Semrush. Use only on **your own sites/domains** — you provide your own keys via BYOK (Bring Your Own Keys). We never see or store your keys. Upstream shapes from `chukhraiartur/seo-keyword-research-tool` + `open-seo` + `crawlseo` + `OpenGSC` + `metehan777/semrush-mcp` + `serpfire/gsc-mcp-server` preserved in `THIRD_PARTY_NOTICES.md` + `upstream/ORIGINAL_LICENSE`. Gold derivative (`src/` outside `upstream/`) is © 2026 Studio AI under `GOLD MCP — COMMERCIAL LICENSE v1.0`.

**Buy Pro — PAID ONLY $29 once via Keygen CE (no free tier):** https://gumroad.com/l/keyword-steroids-gold — all 9 `gold_*` tools require `GOLD_LICENSE_KEY`, fail-closed without it (offline 7-day grace). `gold_setup_check` runs without a license to verify your BYOK keys.

## Quick start

```bash
npx -y keyword-steroids-gold
# or local
npm install
npm run build
node dist/index.js
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "keyword-steroids-gold": {
      "command": "npx",
      "args": ["-y", "keyword-steroids-gold"],
      "env": {
        "GOLD_LICENSE_KEY": "gold_pro_...",
        "GSC_OAUTH_JSON": "{\"type\":\"service_account\",...}",
        "SEMRUSH_API_KEY": "semrush_xxx",
        "BIGQUERY_OAUTH_JSON": "{\"type\":\"service_account\",...}"
      }
    }
  }
}
```

Without GSC/Semrush keys, no-key tools still work. GSC/Semrush tools return `config_error` without their key — no fake data.

## Env vars (BYOK — no fake data, fail-closed)

| Var | Purpose |
|-----|---------|
| `GSC_OAUTH_JSON` | Service-account JSON string or base64 for `gold_gsc_verify` + `gold_gsc_insights` — BYOK, fail-closed without it. See `https://developers.google.com/webmasters/search-console-api` + `https://github.com/serpfire/gsc-mcp-server` auth flow |
| `SEMRUSH_API_KEY` | Semrush API key for `gold_semrush_gap` — BYOK, fail-closed without it. See `https://www.semrush.com/api-documentation/` |
| `BIGQUERY_OAUTH_JSON` / `GCP_SERVICE_ACCOUNT_JSON` | Optional BigQuery service-account JSON for `gold_gsc_insights` `bigquery_sql` (GSC export dataset) — fail-closed without it |
| `GOLD_LICENSE_KEY` / `GOLD_LICENSE` | Gold license — PAID ONLY PRO $29 once (no free tier) via Keygen CE. Or `~/.gold-mcp/license.key` |
| `KEYGEN_ACCOUNT_ID` | Keygen CE account id for online validation (offline 7-day grace) |

`gold_setup_check` always runs and only reports key names `SET/MISSING` (never values). No-key tools throttle 1.2s and never call GSC/Semrush.

## Honest BYOK / no-key split

- **No key (public, free, 1.2s throttle):** `gold_keyword_expand`, `gold_keyword_gap_scan`, `gold_cluster` (pure logic), `gold_crawl_audit`, `gold_keyword_brief`, `gold_keyword_serp_features` — work with no API key (Google Suggest `suggestqueries.google.com/complete/search` + HTML scrape `google.com/search` + pure Jaccard/crawl).
- **BYOK (fail-closed):** `gold_gsc_verify` + `gold_gsc_insights` require `GSC_OAUTH_JSON`; `gold_gsc_insights` with `bigquery_sql` requires `BIGQUERY_OAUTH_JSON`; `gold_semrush_gap` requires `SEMRUSH_API_KEY`. Each throws `config_error` without the key.

## Tools (gold_* — 9 tools + gold_setup_check = 10, all PRO $29 — plus `gold_setup_check` runs without license)

| Tool | What it does |
|------|--------------|
| `gold_keyword_expand` | Hebrew keyword expand — Google Suggest `hl=iw gl=il` (no key) + Related + PAA — `https://suggestqueries.google.com/complete/search?client=firefox&q=...&hl=iw&gl=il` + `google.com/search` HTML |
| `gold_keyword_gap_scan` | Bulk gap scan — 100 queries × `region=il lang=he` HTML heuristic — flags 0-1 shops = OPEN — `google.com/search?hl=iw&gl=il&pws=0` |
| `gold_cluster` | **PURE LOGIC** Jaccard keyword clustering — groups Hebrew keywords by word overlap (threshold 0.35) — no API, no key |
| `gold_crawl_audit` | Crawl audit — BFS up to 50 pages, on-page (title/meta/h1/canonical/robots/viewport/alt) + broken_links + CWV heuristic — no key — steal: `open-seo` 12992 + `crawlseo` 551 |
| `gold_gsc_verify` | GSC verify — checks `site_url` via GSC API `GET /webmasters/v3/sites/{siteUrl}` — **requires `GSC_OAUTH_JSON`** — steal: `serpfire/gsc-mcp-server` 11★ |
| `gold_gsc_insights` | GSC insights — Search Analytics `POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query` (days 28) + optional BigQuery SQL — **requires `GSC_OAUTH_JSON`** (+ `BIGQUERY_OAUTH_JSON` for SQL) — steal: `OpenGSC` 16 + BigQuery 43 |
| `gold_semrush_gap` | Semrush gap — domain vs up to 3 competitors keyword gap — `https://api.semrush.com/?type=domain_organic&key=...&domain=...&database=us&display_limit=20&export_columns=Ph,Nq,Cp,Co` — **requires `SEMRUSH_API_KEY`** — steal: `metehan777/semrush-mcp` 16 MIT |
| `gold_keyword_brief` | POWER: one-page content brief from seed — H1/title/meta formulas, H2 outline from Suggest clusters, word-count band, anchors — no key — `suggestOnce` |
| `gold_keyword_serp_features` | POWER: fetch SERP HTML for keyword and detect PAA box, featured snippet hint, video pack, shopping — no key — `googleHtml` + `paaFromHtml` |
| `gold_setup_check` | Preflight — verifies `GSC_OAUTH_JSON` + `SEMRUSH_API_KEY` + `BIGQUERY_OAUTH_JSON` + `GOLD_LICENSE_KEY` without calling Google/Semrush — **pure logic, counts, no creds leaked** |

All 9 tools are `gold_*` prefixed — PAID ONLY PRO $29 once, fail-closed without `GOLD_LICENSE_KEY`. Destructive writes are not applicable (read/analysis only). Env mapping is `GSC_OAUTH_JSON` / `SEMRUSH_API_KEY` / `BIGQUERY_OAUTH_JSON` ↔ `smithery.yaml` `gscOauthJson` / `semrushApiKey` / `bigqueryOauthJson`.

Self-check is pure logic: `gold_setup_check` counts keys `SET/MISSING` (names only, never values), reports tier, never calls Google/Semrush, never leaks tokens — verified by grep `fetch|GSC_OAUTH|SEMRUSH`.

## Upstream attribution

Derivative shapes from MIT-licensed upstreams (original MIT preserved in `THIRD_PARTY_NOTICES.md` + `upstream/ORIGINAL_LICENSE`):

- `chukhraiartur/seo-keyword-research-tool` — MIT — https://github.com/chukhraiartur/seo-keyword-research-tool — autocomplete + related + PAA shape (SerpAPI-only upstream, we add free HTML scrape `hl=iw & gl=il`, no key)
- `open-seo` 12992★ + `crawlseo` 551 — crawler + on-page + CWV heuristic for `gold_crawl_audit`
- `OpenGSC` 16 + BigQuery 43 — GSC Search Analytics + BigQuery export SQL for `gold_gsc_insights`
- `metehan777/semrush-mcp` 16 MIT — Semrush `domain_organic` gap for `gold_semrush_gap`
- `serpfire/gsc-mcp-server` 11★ — GSC `sites.get` + `GSC_OAUTH_JSON` JSON/base64 handling for `gold_gsc_verify`
- `sundios/people-also-ask` 141 + `seranking/seo-skills` 122 — PAA + Jaccard clustering / throttle pattern

Official APIs used via BYOK (no vendor code copied): Google Suggest `https://suggestqueries.google.com/complete/search` (no key) + Google Search HTML `https://www.google.com/search?hl=iw&gl=il` + GSC API `https://developers.google.com/webmasters/search-console-api` (`https://www.googleapis.com/webmasters/v3/sites/...`) + BigQuery `https://cloud.google.com/bigquery/docs` + Semrush API `https://www.semrush.com/api-documentation/` (`https://api.semrush.com/`).

Gold derivative (`src/` outside `upstream/`) is © 2026 Studio AI under `GOLD MCP — COMMERCIAL LICENSE v1.0 (2026-08-19)` — see `LICENSE` — `LICENSE TIERS: PRO $29 once (PAID ONLY, no free tier) | TEAM $99/mo` via Keygen CE.

## Weekly watch list

Tracked in `docs/MCP-GOLD-MASTER-PLAN-2026-08-19.md` §2 — Keyword MCP gap is Hebrew-specific (`hl=iw gl=il` Suggest + `region=il lang=he` bsearch) before this; full weekly watch URLs live there. Registry-listed via `smithery.yaml` (Smithery) + `mcp.json` (Glama / Pulsemcp / mcp.so / mcp-registry).

## License

`LICENSE` — PRO $29 once, TEAM $99/mo. Upstream MIT remains under MIT. Google/Semrush API terms unchanged.

## See also

- Master plan: `docs/MCP-GOLD-MASTER-PLAN-2026-08-19.md`
- Third-party notices: `THIRD_PARTY_NOTICES.md`
- Google Suggest endpoint: https://suggestqueries.google.com/complete/search?client=firefox&q=example&hl=iw&gl=il
- Google Search Console API: https://developers.google.com/webmasters/search-console-api
- Semrush API docs: https://www.semrush.com/api-documentation/
- Semrush developer docs: https://developer.semrush.com/api/docs/