Seo Dataforseo

---
name: seo-dataforseo
description: DataForSEO MCP wrapper — live SERP results (Google/Bing/Yahoo/YouTube/Images), keyword volume/difficulty/intent/trends, backlink profiles, domain and competitor analytics, on-page/Lighthouse audits, business listings, and AI-visibility (LLM mention) tracking across 9 API modules. Bring-your-own MCP server; degrades to the WebSearch/WebFetch research ladder when not configured. Paid per API call — always cost-check before bulk operations.
allowed-tools: Read, Write, Glob, Grep, Bash
---

# SEO DataForSEO — Live Search Data (MCP Wrapper)

> Every other skill in this kit reasons from static analysis or a WebSearch snapshot — this one talks to the actual DataForSEO API for real SERP positions, real search volume, real backlink counts. Bring your own MCP server; every consuming skill degrades gracefully without it.

## When this skill activates

**Implicit:** "check keyword volume", "live SERP data", "backlink profile for X", "AI visibility check", "keyword difficulty", "real search data", "dataforseo".
**Explicit:** "Use the seo-dataforseo skill to [task]."
**Routed from:** [[seo-cluster]] (keyword volume/difficulty on cluster nodes), [[seo-content]] / [[seo-content-brief]] (search intent, keyword metrics, content-quality signals), [[seo-technical]] (Lighthouse/crawl data, tech-stack detection), [[seo-plan]] (competitor domain intel, traffic estimation), [[seo-geo]] (LLM mention tracking, ChatGPT visibility), [[seo-audit]] (live SERP/backlink/on-page evidence), and the SERP/keyword research ladder in `references/research-tools.md` of [[seo-writing]] (this skill is the top rung).

## Scope

Covers:
- Live Google/Bing/Yahoo organic SERP, Google Images SERP, YouTube search + video deep-analysis
- Keyword ideas/suggestions, search volume, difficulty, intent classification, Google Trends
- Backlink profiles: summary, referring domains, anchors, spam score, timeseries
- Domain/competitor analytics: ranked keywords, competitor discovery, traffic estimation, domain intersection, subdomains, top searches
- On-page technical data: instant-page checks, content parsing, Lighthouse audit, tech-stack detection, WHOIS
- Content analysis (quality, sentiment, phrase trends) and local business listings
- AI visibility / GEO: ChatGPT web-search scraping, cross-platform LLM mention tracking
- Per-call cost awareness for the underlying paid API (this is metered, unlike most skills in this kit)

Does NOT cover:
- Static/manual technical audits when no live crawl is warranted → [[seo-technical]]
- E-E-A-T writing/scoring of the content itself → [[seo-content]]
- Schema markup generation → [[seo-schema]]
- The non-DataForSEO fallback chain (Exa, SerpAPI, WebSearch/WebFetch) → `references/research-tools.md` in [[seo-writing]]

## MCP server (bring your own)

This skill has no bundled server — wire one up like the `mcp-gsc` / `mcp-ga4` wrappers in `skills/automation/`:

- **Server:** any MCP server exposing the DataForSEO API surface (e.g. the official `dataforseo-mcp-server`, or a community equivalent). Configure via `/ck:use-mcp dataforseo`.
- **Required env:** `DATAFORSEO_LOGIN`, `DATAFORSEO_PASSWORD` (or an API key, depending on the server). Env-only — never paste credentials into a plan file or prompt.
- **Availability check:** before calling any tool below, confirm one of them (e.g. `serp_organic_live_advanced`) is actually present in the tool list. If not, say so and route to the manual fallback — do not guess at data.

## Cost awareness (this API is metered)

Unlike GSC/GA4-style wrappers, DataForSEO bills per call. Be deliberate:

- Prefer bulk endpoints (`*_bulk_*`) over N single calls.
- Use default parameters (US, English, `live_regular` over `live_advanced`) unless the user's market requires otherwise.
- Don't re-fetch the same keyword/domain within a session — reuse what was already pulled.
- **Before anything in the "always confirm" tier below, or before a batch of more than ~10 calls, tell the user the endpoint, the approximate cost from `references/cost-tiers.md`, and ask for a go-ahead.** There is no automated budget tracker in this kit — the confirmation step is manual, every time.
- Note the actual source in output as "DataForSEO (live)" so it's distinguishable from a WebSearch-derived estimate.

**Always confirm before calling**, regardless of batch size — these are the ones people run up a bill on by accident:
- `backlinks_backlinks` (can return large result sets)
- `backlinks_domain_intersection` (multi-domain, expensive)
- `ai_optimization_chat_gpt_scraper` (LLM scraping)
- `ai_opt_llm_ment_search` (LLM mention tracking)
- Any `serp_google_images_live_*` call using `site:`/`filetype:` operators (5x cost multiplier)

Full pricing table, budget presets, and cost-reduction tips: `references/cost-tiers.md`.

---

## SERP analysis

**Organic SERP** — live Google (also Bing/Yahoo via the `se` parameter) results. Tool: `serp_organic_live_advanced`. Defaults: `location_code=2840` (US), `language_code=en`, `device=desktop`, `depth=100`. Returns rank, URL, title, description, domain, featured snippets, AI Overview references, People Also Ask.

**Google Images SERP** — which images/domains rank for a keyword. Tool: `serp_google_images_live_advanced`. Params: keyword (required), depth (max 700, billed per 100-result increment), search_param (e.g. `site:example.com` — **5x cost**, warn first). Returns position, title, alt text, source page URL, image URL, domain. Worth pairing with: domain dominance (top-10 domains by image-position count), alt-text patterns, format distribution (WebP/JPEG/PNG from the URL extension), and gap identification (keywords where the user ranks organically but has no image presence).

**YouTube SERP** — Tool: `serp_youtube_organic_live_advanced`. Useful for GEO: YouTube mentions are one of the stronger correlates with AI-search citations found in third-party studies.

**YouTube video deep-analysis** — info, comments, subtitles for a specific video. Tools: `serp_youtube_video_info_live_advanced`, `serp_youtube_video_comments_live_advanced`, `serp_youtube_video_subtitles_live_advanced`. Param: `video_id`. Treat any specific correlation number (e.g. "0.737") as methodology-dependent, not a fixed constant — cite the study if quoting a figure, otherwise describe the direction only.

## Keyword research

- **Ideas/suggestions/related terms** from a seed — `dataforseo_labs_google_keyword_ideas`, `dataforseo_labs_google_keyword_suggestions`, `dataforseo_labs_google_related_keywords`. Defaults: `location_code=2840`, `language_code=en`, `limit=50`. Returns keyword, volume, CPC, competition, difficulty, trend.
- **Search volume** for a keyword list — `kw_data_google_ads_search_volume`. Returns monthly volume, CPC, competition, monthly trend series.
- **Keyword difficulty (bulk)** — `dataforseo_labs_bulk_keyword_difficulty`. Returns a 0–100 score with an Easy/Medium/Hard/Very Hard interpretation.
- **Search intent** — `dataforseo_labs_search_intent`. Classifies informational/navigational/commercial/transactional with a confidence score.
- **Trends** — `kw_data_google_trends_explore`. Params: keywords, location, date range. Returns a time series, trend direction, seasonality signal.

This is the block [[seo-cluster]] and [[seo-content-brief]] want for real numbers instead of a WebSearch-inferred guess.

## Domain & competitor analysis

- **Backlink profile** — `backlinks_summary`, `backlinks_backlinks`, `backlinks_anchors`, `backlinks_referring_domains`, `backlinks_bulk_spam_score`, `backlinks_timeseries_summary`. Returns total backlinks, referring domains, domain rank, spam score, top anchors, new/lost over time, dofollow ratio.
- **Competitors + traffic** — `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_rank_overview`, `dataforseo_labs_bulk_traffic_estimation`. Returns competitor domains, keyword overlap %, estimated traffic, domain rank.
- **Ranked keywords** — `dataforseo_labs_google_ranked_keywords`, `dataforseo_labs_google_relevant_pages`. Returns keyword, position, URL, volume, traffic share, SERP features.
- **Intersection** (2–20 domains) — `dataforseo_labs_google_domain_intersection`, `backlinks_domain_intersection`. Returns shared keywords per domain position, shared backlink sources, unique keywords.
- **Bulk traffic estimation** — `dataforseo_labs_bulk_traffic_estimation`. Domain → estimated organic traffic, traffic cost, top keywords.
- **Subdomains** — `dataforseo_labs_google_subdomains`. Subdomain → ranked-keyword count, estimated traffic, organic cost.
- **Top searches mentioning a domain** — `dataforseo_labs_google_top_searches`. Query → volume, domain position, SERP features, traffic share.

Feeds [[seo-plan]]'s competitive-intelligence prioritization and [[seo-audit]]'s backlink evidence.

## Technical / on-page

- **On-page analysis** — `on_page_instant_pages` (status codes, meta tags, content size, timing, broken links), `on_page_content_parsing` (extracted text, word count, structure), `on_page_lighthouse` (performance/accessibility/best-practices/SEO scores, Core Web Vitals).
- **Tech-stack detection** — `domain_analytics_technologies_domain_technologies`. Returns technology, version, category (CMS/analytics/CDN/framework).
- **WHOIS** — `domain_analytics_whois_overview`. Registrar, creation/expiry date, nameservers, registrant (if public).

Feeds [[seo-technical]] with real crawl data instead of a manual spot-check.

## Content & business data

- **Content analysis** — `content_analysis_search` (topic search with quality scores + sentiment), `content_analysis_summary` (URL → readability/quality metrics), `content_analysis_phrase_trends` (phrase volume over time).
- **Business listings** — `business_data_business_listings_search`. Keyword (+ optional location) → name, category, address, phone, domain, rating, review count, claimed status. Local-SEO competitive scan.

## AI visibility / GEO

- **ChatGPT scrape** — `ai_optimization_chat_gpt_scraper`. Query → response content, cited sources/URLs, referenced domains. Shows which sources ChatGPT cites for a target keyword; pair with GSC's AI Overview / AI Mode reports where available (see [[seo-google]]). Location lookup: `ai_optimization_chat_gpt_scraper_locations`.
- **LLM mention tracking** — `ai_opt_llm_ment_search` (mentions of a brand/keyword across LLM responses), `ai_opt_llm_ment_top_domains` (most-cited domains for the topic), `ai_opt_llm_ment_top_pages` (most-cited specific pages), `ai_opt_llm_ment_agg_metrics` (aggregate volume/trend). Cross-model comparison: `ai_opt_llm_ment_cross_agg_metrics`. Location/model lookups: `ai_opt_llm_ment_loc_and_lang`, `ai_optimization_llm_models`.

This is the strongest available signal for [[seo-geo]]'s citation-rate measurement — it's the only source in this kit that observes actual LLM output rather than inferring citability from content structure.

## Additional utility tools

Location lookups, historical-data variants, bulk operations, and filter-option tools that don't have a dedicated section above are catalogued in `references/tool-catalog.md` — load it when the six sections above don't cover the specific need.

## Error handling

| Situation | Response |
|---|---|
| MCP server not connected / tool not in list | Say so plainly; point to "MCP server (bring your own)" above; do not fabricate a result |
| Auth failure | Report invalid credentials; check `DATAFORSEO_LOGIN`/`DATAFORSEO_PASSWORD` (or key) in the MCP config |
| Rate limit hit | Report the limit and suggest waiting before retrying |
| No results | Report "no data found" — never guess a plausible-looking number to fill the gap |
| Invalid location/language code | Use the relevant `*_locations` lookup tool to find the correct code |

## Manual fallback (no MCP server configured)

DataForSEO has no CSV-export equivalent like GSC/GA4 — when the server isn't available, don't try to approximate its numbers by hand. Instead, drop down the ladder documented in `references/research-tools.md` of [[seo-writing]]: SerpAPI MCP → Exa → `WebSearch` → model knowledge, and **label the output** `[UNVERIFIED — no live SERP/keyword data]` so downstream consumers ([[seo-cluster]], [[seo-content-brief]], [[seo-plan]]) know to sanity-check before acting on it. Never invent a search-volume or difficulty number to fill the gap.

## Key concepts

- **Metered API** — every call costs money; this is the one skill in the kit where "just check it live" isn't free. Batch, cache within-session, and confirm before the expensive tier.
- **Live vs. Labs data** — `serp_*` and `kw_data_*` tools hit the search engine or ad platform directly (freshest, costs more); `dataforseo_labs_*` tools are DataForSEO's own derived/cached datasets (cheaper, near-real-time, better for bulk/competitive work).
- **GEO signal, not SEO signal** — the AI-visibility tools (`ai_opt_llm_ment_*`, `ai_optimization_chat_gpt_scraper`) measure LLM citation behavior, a distinct and much newer surface than organic ranking; treat correlational claims about it as provisional.

## Output

- Inline data tables in the conversation (rank/volume/difficulty/backlink comparisons), formatted with issues prioritized Critical > High > Medium > Low where applicable.
- When feeding another skill's artifact — e.g. `plans/marketing/<site>/pipeline.md` ([[seo-cluster]]), `briefs/<slug>.md` ([[seo-content-brief]]), `audit-report.md` ([[seo-audit]]) — write the live numbers into that file, tagged "DataForSEO (live)" so a reader can tell it apart from a WebSearch estimate.
- Standalone use: `plans/marketing/<campaign>/seo-dataforseo.md`.

## Cross-references

- `plans/marketing-context.md` — required hub (market/locale informs `location_code`/`language_code` defaults)
- [[seo-writing]] `references/research-tools.md` — the research ladder this skill sits at the top of, and its manual-fallback labeling convention
- [[seo-cluster]], [[seo-content-brief]], [[seo-plan]] — consumers of keyword/competitor metrics
- [[seo-technical]] — consumer of Lighthouse/crawl/tech-stack data
- [[seo-geo]] — consumer of AI-visibility/LLM-mention data
- [[seo-audit]] — consumer of live SERP/backlink/on-page evidence
- `skills/automation/mcp-gsc/SKILL.md`, `skills/automation/mcp-ga4/SKILL.md` — sibling MCP-wrapper skills; same bring-your-own-server + manual-fallback convention
- `references/cost-tiers.md` — pricing table, budget presets, cost-reduction tips
- `references/tool-catalog.md` — utility MCP tools without a dedicated section above

## Provenance

Imported from `AgriciDaniel/claude-seo` (`seo-dataforseo`, v2.2.4) and adapted for KitForge. Adaptations: dropped the `./extensions/dataforseo/install.sh` installer and the `claude-seo run dataforseo_costs.py` cost-tracking CLI (neither exists in ClauKit) in favor of the manual, judgment-based cost-confirmation flow described above and the bring-your-own-MCP-server convention already used by `skills/automation/mcp-gsc` and `mcp-ga4`; dropped the source's bespoke `/seo dataforseo <command>` slash-command surface (this kit routes to the skill via `/mk:seo` + implicit activation, not a per-tool subcommand router); all MCP tool names, API module coverage, defaults, and cost figures are preserved from source. `references/cost-tiers.md` and `references/tool-catalog.md` are ported with the same script-removal adaptation.