---
name: "DataForSEO: live SEO data (extension)"
repo: https://github.com/agricidaniel/claude-seo
source: https://github.com/agricidaniel/claude-seo/blob/HEAD/skills/seo-dataforseo/SKILL.md
license: "MIT"
install: "npx skills add agricidaniel/claude-seo --skill seo-dataforseo"
page: https://100xlab.com/resources/agent-skills/agricidaniel-claude-seo--seo-dataforseo--ptos5y
---

# DataForSEO: Live SEO Data (Extension)

Live search data via the DataForSEO MCP server. Provides real-time SERP results
(organic + images), keyword metrics, backlink profiles, on-page analysis, content
analysis, business listings, AI visibility checking, and LLM mention tracking
across 9 API modules with 79+ MCP tools.

## Prerequisites

This skill requires the DataForSEO extension to be installed:
```bash
./extensions/dataforseo/install.sh
```

**Check availability:** Before using any DataForSEO tool, verify the MCP server
is connected by checking if `serp_organic_live_advanced` or any DataForSEO tool
is available. If tools are not available, inform the user the extension is not
installed and provide install instructions.

## API Credit Awareness

DataForSEO charges per API call. Be efficient:
- Prefer bulk endpoints over multiple single calls
- Use default parameters (US, English) unless user specifies otherwise
- Cache results mentally within a session; don't re-fetch the same data
- Warn user before running expensive operations (full backlink crawls, large keyword lists)

## Cost Guardrails

**Before every DataForSEO MCP call**, run cost estimation:
```
claude-seo run dataforseo_costs.py check <endpoint> [--count N]
```

- If `"status": "approved"` → proceed with the API call
- If `"status": "needs_approval"` → show the cost estimate to the user and ask for confirmation before proceeding
- If `"status": "blocked"` → inform the user that the daily budget limit would be exceeded; do NOT proceed

**After each API call completes**, log the cost:
```
claude-seo run dataforseo_costs.py log <endpoint> <actual_cost>
```

**User commands for cost management:**
- `/seo dataforseo costs today` → show today's spending breakdown
- `/seo dataforseo costs summary` → show 7-day spending history
- `/seo dataforseo costs config --mode threshold --threshold 0.50` → configure approval mode

Load `references/cost-tiers.md` for the full pricing table, budget presets, and cost reduction tips.

## Quick Reference

| Command | What it does |
|---------|-------------|
| `/seo dataforseo serp <keyword>` | Google organic SERP results |
| `/seo dataforseo serp-images <keyword>` | Google Images SERP results |
| `/seo dataforseo serp-youtube <keyword>` | YouTube search results |
| `/seo dataforseo youtube <video_id>` | YouTube video deep analysis |
| `/seo dataforseo keywords <seed>` | Keyword ideas and suggestions |
| `/seo dataforseo volume <keywords>` | Search volume for keywords |
| `/seo dataforseo difficulty <keywords>` | Keyword difficulty scores |
| `/seo dataforseo intent <keywords>` | Search intent classification |
| `/seo dataforseo trends <keyword>` | Google Trends data |
| `/seo dataforseo backlinks <domain>` | Full backlink profile |
| `/seo dataforseo competitors <domain>` | Competitor domain analysis |
| `/seo dataforseo ranked <domain>` | Ranked keywords for domain |
| `/seo dataforseo intersection <domains>` | Keyword/backlink overlap |
| `/seo dataforseo traffic <domains>` | Bulk traffic estimation |
| `/seo dataforseo subdomains <domain>` | Subdomains with ranking data |
| `/seo dataforseo top-searches <domain>` | Top queries mentioning domain |
| `/seo dataforseo onpage <url>` | On-page analysis (Lighthouse + parsing) |
| `/seo dataforseo tech <domain>` | Technology stack detection |
| `/seo dataforseo whois <domain>` | WHOIS registration data |
| `/seo dataforseo content <keyword/url>` | Content analysis and trends |
| `/seo dataforseo listings <keyword>` | Business listings search |
| `/seo dataforseo ai-scrape <query>` | ChatGPT web scraper for GEO |
| `/seo dataforseo ai-mentions <keyword>` | LLM mention tracking for GEO |

---

## SERP Analysis

### `/seo dataforseo serp <keyword>`

Fetch live Google organic search results.

**MCP tools:** `serp_organic_live_advanced`

**Default parameters:** location_code=2840 (US), language_code=en, device=desktop, depth=100

**Also supports:** The `serp_organic_live_advanced` tool supports Google, Bing, and Yahoo via the `se` parameter. Specify "bing" or "yahoo" to switch search engines.

**Output:** Rank, URL, title, description, domain, featured snippets, AI overview references, People Also Ask.

### `/seo dataforseo serp-youtube <keyword>`

Fetch YouTube search results. Valuable for GEO. YouTube mentions correlate most strongly with AI citations.

**MCP tools:** `serp_youtube_organic_live_advanced`

**Output:** Video title, channel, views, upload date, description, URL.

### `/seo dataforseo youtube <video_id>`

Deep analysis of a specific YouTube video: info, comments, and subtitles. Some third-party studies report a 0.737 correlation between YouTube mentions and AI visibility, so treat this as a methodology-dependent GEO signal.

**MCP tools:** `serp_youtube_video_info_live_advanced`, `serp_youtube_video_comments_live_advanced`, `serp_youtube_video_subtitles_live_advanced`

**Parameters:** video_id (the YouTube video ID, e.g., "dQw4w9WgXcQ")

**Output:** Video metadata (title, channel, views, likes, description), top comments with engagement, subtitle/transcript text.

### `/seo dataforseo serp-images <keyword>`

Fetch live Google Images search results. See which images rank for a keyword,
which domains dominate image results, and identify visual content opportunities.

**MCP tools:** `serp_google_images_live_advanced`

**Default parameters:** location_code=2840 (US), language_code=en, device=desktop, depth=100

**Parameters:** keyword (required), depth (optional, max 700, billed per 100-result increment), search_param (optional, e.g. "site:example.com")

**Cost warning:** Using `site:` or `filetype:` operators incurs **5x API cost**. Warn user before running filtered queries.

**Output:** Position, title, alt text, source page URL, direct image URL, domain, encoded URL.

**Analysis to provide:**
- Domain dominance: which sites own the most image positions (top 10 domains by count)
- Alt text patterns: common title/alt text patterns in top-ranking images
- Format distribution: WebP vs JPEG vs PNG in top results (infer from image_url extension)
- Opportunity identification: keywords where user has organic rankings but no image presence

---

## Keyword Research

### `/seo dataforseo keywords <seed>`

Generate keyword ideas, suggestions, and related terms from a seed keyword.

**MCP tools:** `dataforseo_labs_google_keyword_ideas`, `dataforseo_labs_google_keyword_suggestions`, `dataforseo_labs_google_related_keywords`

**Default parameters:** location_code=2840 (US), language_code=en, limit=50

**Output:** Keyword, search volume, CPC, competition level, keyword difficulty, trend.

### `/seo dataforseo volume <keywords>`

Get search volume and metrics for a list of keywords.

**MCP tools:** `kw_data_google_ads_search_volume`

**Parameters:** keywords (array, comma-separated), location_code, language_code

**Output:** Keyword, monthly search volume, CPC, competition, monthly trend data.

### `/seo dataforseo difficulty <keywords>`

Calculate keyword difficulty scores for ranking competitiveness.

**MCP tools:** `dataforseo_labs_bulk_keyword_difficulty`

**Parameters:** keywords (array), location_code, language_code

**Output:** Keyword, difficulty score (0-100), interpretation (Easy/Medium/Hard/Very Hard).

### `/seo dataforseo intent <keywords>`

Classify keywords by user search intent.

**MCP tools:** `dataforseo_labs_search_intent`

**Parameters:** keywords (array), location_code, language_code

**Output:** Keyword, intent type (informational, navigational, commercial, transactional), confidence score.

### `/seo dataforseo trends <keyword>`

Analyze keyword trends over time using Google Trends data.

**MCP tools:** `kw_data_google_trends_explore`

**Parameters:** keywords (array), location_code, date_from, date_to, language_code

**Output:** Keyword, time series data, trend direction, seasonality signals.

---

## Domain & Competitor Analysis

### `/seo dataforseo backlinks <domain>`

Comprehensive backlink profile analysis.

**MCP tools:** `backlinks_summary`, `backlinks_backlinks`, `backlinks_anchors`, `backlinks_referring_domains`, `backlinks_bulk_spam_score`, `backlinks_timeseries_summary`

**Default parameters:** limit=100 per sub-call

**Output:** Total backlinks, referring domains, domain rank, spam score, top anchors, new/lost backlinks over time, dofollow ratio, top referring domains.

### `/seo dataforseo competitors <domain>`

Identify competing domains and estimate traffic.

**MCP tools:** `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_rank_overview`, `dataforseo_labs_bulk_traffic_estimation`

**Output:** Competitor domains, keyword overlap %, estimated traffic, domain rank, common keywords.

### `/seo dataforseo ranked <domain>`

List keywords a domain ranks for with positions and page data.

**MCP tools:** `dataforseo_labs_google_ranked_keywords`, `dataforseo_labs_google_relevant_pages`

**Default parameters:** limit=100, location_code=2840

**Output:** Keyword, position, URL, search volume, traffic share, SERP features.

### `/seo dataforseo intersection <domain1> <domain2> [...]`

Find shared keywords and backlink sources across 2-20 domains.

**MCP tools:** `dataforseo_labs_google_domain_intersection`, `backlinks_domain_intersection`

**Parameters:** domains (2-20 array)

**Output:** Shared keywords with positions per domain, shared backlink sources, unique keywords per domain.

### `/seo dataforseo traffic <domains>`

Estimate organic search traffic for one or more domains.

**MCP tools:** `dataforseo_labs_bulk_traffic_estimation`

**Parameters:** domains (array)

**Output:** Domain, estimated organic traffic, estimated traffic cost, top keywords.

### `/seo dataforseo subdomains <domain>`

Enumerate subdomains with their ranking data and traffic estimates.

**MCP tools:** `dataforseo_labs_google_subdomains`

**Parameters:** target (domain), location_code, language_code

**Output:** Subdomain, ranked keywords count, estimated traffic, organic cost.

### `/seo dataforseo top-searches <domain>`

Find the most popular search queries that mention a specific domain in results.

**MCP tools:** `dataforseo_labs_google_top_searches`

**Parameters:** target (domain), location_code, language_code

**Output:** Query, search volume, domain position, SERP features, traffic share.

---

## Technical / On-Page

### `/seo dataforseo onpage <url>`

Run on-page analysis including Lighthouse audit and content parsing.

**MCP tools:** `on_page_instant_pages`, `on_page_content_parsing`, `on_page_lighthouse`

**Usage:**
- `on_page_instant_pages`:Quick page analysis (status codes, meta tags, content size, page timing, broken links, on-page checks)
- `on_page_content_parsing`:Extract and parse page content (plain text, word count, structure)
- `on_page_lighthouse`:Full Lighthouse audit (performance score, accessibility, best practices, SEO, Core Web Vitals)

**Output:** Pages crawled, status codes, meta tags, titles, content size, load times, Lighthouse scores, broken links, resource analysis.

### `/seo dataforseo tech <domain>`

Detect technologies used on a domain.

**MCP tools:** `domain_analytics_technologies_domain_technologies`

**Output:** Technology name, version, category (CMS, analytics, CDN, framework, etc.).

### `/seo dataforseo whois <domain>`

Retrieve WHOIS registration data.

**MCP tools:** `domain_analytics_whois_overview`

**Output:** Registrar, creation date, expiration date, nameservers, registrant info (if public).

---

## Content & Business Data

### `/seo dataforseo content <keyword/url>`

Analyze content quality, search for content by topic, and track phrase trends.

**MCP tools:** `content_analysis_search`, `content_analysis_summary`, `content_analysis_phrase_trends`

**Parameters:** keyword (for search/trends) or URL (for summary)

**Output:** Content matches with quality scores, sentiment analysis, readability metrics, phrase trend data over time.

### `/seo dataforseo listings <keyword>`

Search business listings for local SEO competitive analysis.

**MCP tools:** `business_data_business_listings_search`

**Parameters:** keyword, location (optional)

**Output:** Business name, description, category, address, phone, domain, rating, review count, claimed status.

---

## AI Visibility / GEO

### `/seo dataforseo ai-scrape <query>`

Scrape what ChatGPT web search returns for a query. ChatGPT visibility check: see which sources ChatGPT cites for your target keywords. Check Google AI Overviews and AI Mode with GSC gen-AI reports when available.

**MCP tools:** `ai_optimization_chat_gpt_scraper`

**Parameters:** query, location_code (optional), language_code (optional). Use `ai_optimization_chat_gpt_scraper_locations` to look up available locations.

**Output:** ChatGPT response content, cited sources/URLs, referenced domains.

### `/seo dataforseo ai-mentions <keyword>`

Track how LLMs mention brands, domains, and topics. Critical for GEO. Measures actual AI visibility across multiple LLM platforms.

**MCP tools:** `ai_opt_llm_ment_search`, `ai_opt_llm_ment_top_domains`, `ai_opt_llm_ment_top_pages`, `ai_opt_llm_ment_agg_metrics`

**Parameters:** keyword, location_code (optional), language_code (optional). Use `ai_opt_llm_ment_loc_and_lang` for available locations/languages and `ai_optimization_llm_models` for supported LLM models.

**Workflow:**
1. Search LLM mentions with `ai_opt_llm_ment_search` (find mentions of a brand/keyword across LLM responses)
2. Get top cited domains with `ai_opt_llm_ment_top_domains` (which domains are most cited for this topic)
3. Get top cited pages with `ai_opt_llm_ment_top_pages` (which specific pages are most cited)
4. Get aggregate metrics with `ai_opt_llm_ment_agg_metrics` (overall mention volume, trends)

**Output:** LLM mention count, top cited domains with frequency, top cited pages, mention trends over time, cross-platform visibility scores.

**Advanced:** Use `ai_opt_llm_ment_cross_agg_metrics` for cross-model comparison (how mentions differ across ChatGPT, Claude, Perplexity, etc.).

---

## Available Utility Tools

Additional DataForSEO MCP tools are available for internal use but do not have dedicated commands. Load `references/tool-catalog.md` when you need to find a specific utility tool (location lookups, bulk operations, historical data, filter options).

## Cross-Skill Integration

When DataForSEO MCP tools are available, other claude-seo skills can leverage live data:

- **seo-audit**:Spawn `seo-dataforseo` agent for real SERP, backlink, on-page, and listings data
- **seo-technical**:Use `on_page_instant_pages` / `on_page_lighthouse` for real crawl data, `domain_analytics_technologies_domain_technologies` for stack detection
- **seo-content**:Use `kw_data_google_ads_search_volume`, `dataforseo_labs_bulk_keyword_difficulty`, `dataforseo_labs_search_intent` for real keyword metrics, `content_analysis_summary` for content quality
- **seo-page**:Use `serp_organic_live_advanced` for real SERP positions, `backlinks_summary` for link data
- **seo-images**:Use `serp_google_images_live_advanced` for competitor image SERP data, cross-reference with on-page image audit
- **seo-geo**:Use `ai_optimization_chat_gpt_scraper` for real ChatGPT visibility, `ai_opt_llm_ment_search` for LLM mention tracking
- **seo-plan**:Use `dataforseo_labs_google_competitors_domain`, `dataforseo_labs_google_domain_intersection`, `dataforseo_labs_bulk_traffic_estimation` for real competitive intelligence

## Error Handling

- **MCP server not connected**: Report that DataForSEO extension is not installed or MCP server is unreachable. Suggest running `./extensions/dataforseo/install.sh`
- **API authentication failed**: Report invalid credentials. Suggest checking DataForSEO API login/password in MCP config
- **Rate limit exceeded**: Report the limit hit and suggest waiting before retrying
- **No results returned**: Report "no data found" for the query rather than guessing. Suggest broadening the query or checking location/language codes
- **Invalid location code**: Report the error and suggest using the locations lookup tool to find the correct code

## Output Formatting

Match existing claude-seo output patterns:
- Use tables for comparative data
- Prioritize issues as Critical > High > Medium > Low
- Include specific, actionable recommendations
- Show scores as XX/100 where applicable
- Note data source as "DataForSEO (live)" to distinguish from static analysis

---

## Supporting file: LICENSE.txt

MIT License - see repository root LICENSE file for complete terms.

Copyright (c) 2026 AgriciDaniel
https://github.com/AgriciDaniel/claude-seo

---

## Supporting file: references/cost-tiers.md

# DataForSEO API Cost Reference

## Pricing Tiers (USD per call, standard queue)

| Category | Endpoint | Cost/Call | Notes |
|----------|----------|-----------|-------|
| **SERP** | `serp_*_live_advanced` | $0.002 | Per 100 results |
| **SERP** | `serp_*_live_regular` | $0.001 | Lightweight |
| **SERP Images** | `serp_google_images_live_*` | $0.002 | 5x with site:/filetype: operators |
| **Keywords** | `kw_data_google_ads_search_volume` | $0.05 | Per batch of keywords |
| **Keywords** | `kw_data_google_trends_explore` | $0.01 | Per query |
| **Labs** | `dataforseo_labs_*_keyword_*` | $0.05 | Ideas, suggestions, related |
| **Labs** | `dataforseo_labs_bulk_*` | $0.01 | Difficulty, traffic |
| **Labs** | `dataforseo_labs_*_domain_*` | $0.05 | Competitors, intersection |
| **On-Page** | `on_page_instant_pages` | $0.01 | Quick analysis |
| **On-Page** | `on_page_lighthouse` | $0.02 | Full Lighthouse |
| **Backlinks** | `backlinks_*` | $0.02 | Per sub-call |
| **Content** | `content_analysis_*` | $0.02 | Search, summary, trends |
| **Business** | `business_data_*` | $0.05 | Listings search |
| **AI/GEO** | `ai_optimization_chat_gpt_scraper`, `ai_opt_llm_ment_*` | $0.05 | ChatGPT scraper, LLM mentions |
| **Merchant** | `merchant_*` | $0.02 | Google Shopping, Amazon |
| **Domain** | `domain_analytics_whois_*` | $0.005 | WHOIS data |
| **Domain** | `domain_analytics_technologies_*` | $0.01 | Tech stack |

## Budget Presets

| Preset | Daily Limit | Threshold | Mode | Best For |
|--------|------------|-----------|------|----------|
| **Conservative** | $2.00 | $0.10 | threshold | Learning, testing |
| **Standard** | $10.00 | $0.50 | threshold | Regular audits |
| **Aggressive** | $50.00 | $2.00 | threshold | Agency bulk work |
| **Unlimited** | $999.00 | -- | none | Trusted pipelines |

Configure with: `claude-seo run dataforseo_costs.py config --mode threshold --threshold 0.50 --daily-limit 10.00`

## Cost Reduction Tips

- Use `live_regular` instead of `live_advanced` when full SERP features aren't needed (50% savings)
- Batch keywords into single `search_volume` calls instead of individual SERP lookups
- Use `standard` task queue instead of `live` for non-urgent analysis (60-80% savings)
- Avoid `site:` and `filetype:` operators in image SERP queries (5x cost multiplier)
- Cache session results — don't re-fetch the same keyword/domain within a session

## Approval Flow

Before any DataForSEO MCP call:
1. Run `claude-seo run dataforseo_costs.py check <endpoint> [--count N]`
2. If `status: "approved"` → proceed
3. If `status: "needs_approval"` → show cost to user, ask to confirm
4. If `status: "blocked"` → inform user daily limit would be exceeded
5. After call completes, log: `claude-seo run dataforseo_costs.py log <endpoint> <cost>`

## Warn Endpoints

These endpoints always require user confirmation regardless of approval mode:
- `backlinks_backlinks` (can generate large result sets)
- `backlinks_domain_intersection` (expensive multi-domain comparison)
- `ai_optimization_chat_gpt_scraper` (ChatGPT web scraping)
- `ai_opt_llm_ment_search` (LLM mention tracking)
- `merchant_amazon_products_search` (Amazon product data)

---

## Supporting file: references/tool-catalog.md

# DataForSEO MCP Tool Catalog

> Load this reference when you need to find a specific DataForSEO MCP tool
> that is not covered by the main SKILL.md commands. These are utility tools
> available for internal use but without dedicated `/seo dataforseo` commands.

## SERP Utilities

- `serp_locations`: Location code lookups for SERP queries
- `serp_youtube_locations`: Location code lookups for YouTube queries

## Keyword Data Utilities

- `kw_data_google_ads_locations`: Location lookups for keyword data
- `kw_data_dfs_trends_demography`: Demographic data for trend analysis
- `kw_data_dfs_trends_subregion_interests`: Subregion interest data for trends
- `kw_data_dfs_trends_explore`: DFS proprietary trends data
- `kw_data_google_trends_categories`: Google Trends category lookups

## DataForSEO Labs Utilities

- `dataforseo_labs_google_keyword_overview`: Quick keyword metrics overview
- `dataforseo_labs_google_historical_serp`: Historical SERP results for a keyword
- `dataforseo_labs_google_serp_competitors`: Competitors for a specific SERP
- `dataforseo_labs_google_keywords_for_site`: Keywords a site ranks for (alternative to ranked)
- `dataforseo_labs_google_page_intersection`: Page-level intersection analysis
- `dataforseo_labs_google_historical_rank_overview`: Historical domain rank data
- `dataforseo_labs_google_historical_keyword_data`: Historical keyword metrics
- `dataforseo_labs_available_filters`: Available filter options for Labs endpoints

## Backlinks Utilities

- `backlinks_competitors`: Find domains with similar backlink profiles
- `backlinks_bulk_backlinks`: Bulk backlink counts for multiple targets
- `backlinks_bulk_new_lost_referring_domains`: Bulk new/lost referring domains
- `backlinks_bulk_new_lost_backlinks`: Bulk new/lost backlinks
- `backlinks_bulk_ranks`: Bulk rank overview for multiple targets
- `backlinks_bulk_referring_domains`: Bulk referring domain counts
- `backlinks_domain_pages_summary`: Summary of pages on a domain
- `backlinks_domain_pages`: List pages on a domain with backlink data
- `backlinks_page_intersection`: Shared backlink sources at page level
- `backlinks_referring_networks`: Referring network analysis
- `backlinks_timeseries_new_lost_summary`: Track new/lost backlinks over time
- `backlinks_bulk_pages_summary`: Bulk page summaries
- `backlinks_available_filters`: Available filter options for Backlinks endpoints

## Domain Analytics Utilities

- `domain_analytics_whois_available_filters`: WHOIS filter options
- `domain_analytics_technologies_available_filters`: Technology detection filter options

## AI Optimization Utilities

- `ai_opt_kw_data_loc_and_lang`: AI optimization keyword data locations/languages
- `ai_optimization_keyword_data_search_volume`: AI-specific keyword volume data
- `ai_optimization_llm_response`: Direct LLM response analysis
- `ai_optimization_llm_mentions_filters`: Available filters for LLM mentions
- `ai_optimization_chat_gpt_scraper_locations`: Available locations for ChatGPT scraper