SERP Analysis
Fetches live SERP data for a keyword from Ahrefs, showing ranking pages with
DR scores, traffic estimates, and content angle analysis. WebMCP enriches page
titles when available; Ahrefs-only mode is the primary operating mode.
References
@skills/seo/references/mcp-degradation.md
@skills/seo/references/ahrefs-api-reference.md
Inputs
keyword: The search query to analyze (required). Example: "best project management software"
MCP Check
Before proceeding, verify MCPs are available:
Primary check (required):
- Use ToolSearch with query
+ahrefs
- If tools returned → Ahrefs MCP is available, proceed to Execution
- If no tools returned → display the Ahrefs MCP error template from
references/mcp-degradation.md and stop
Secondary check (non-blocking):
- Use ToolSearch with query
+webmcp
- If tools returned → note "WebMCP available — will enrich top 3 URLs with page titles"
- If no tools returned → note "WebMCP not connected — running Ahrefs-only mode" and proceed
Execution
Step 1 — Discover serp-overview parameter schema
Use ToolSearch with query serp-overview to inspect the tool definition and
discover its parameter names. The keyword parameter may be named keyword,
query, or term — do not assume. Use the exact parameter name found in the
schema for the call in Step 2.
Step 2 — Call serp-overview
Call mcp__claude_ai_ahrefs__serp-overview using the parameter name discovered
in Step 1 with the user's keyword as the value.
Returns: list of ranking pages with fields that may include url, domain_rating,
traffic, traffic_cost, position, title.
Step 3 — WebMCP enrichment (only if WebMCP available from MCP Check)
For the top 3 URLs from the SERP results, use WebMCP to fetch each page and
extract:
- Page
<title> tag content
- First
<h1> tag content
Use these to determine the content angle each top-ranking page is targeting.
If WebMCP is unavailable, skip this step entirely — do not attempt the calls.
Step 4 — CRITICAL: Monetary conversion
Any fields ending in _cost, _value, or cpc are returned in CENTS.
Divide by 100 before display. Format as USD with comma thousands separators.
Example: traffic_cost = 125000 → display as $1,250
Step 5 — SERP difficulty assessment
Calculate average DR of the top 10 ranking pages. Use this scale:
- Average DR < 20 → "Low difficulty — achievable for new or low-authority sites"
- Average DR 20–40 → "Moderate difficulty — requires solid backlink profile"
- Average DR 41–60 → "High difficulty — needs established authority"
- Average DR > 60 → "Very high difficulty — major brands dominating SERP"
Output Format
## SERP Analysis: "{keyword}"
**SERP Difficulty:** {assessment} (avg DR of top 10: {avg_dr})
**Data source:** Ahrefs serp-overview{, enriched via WebMCP | — Ahrefs-only mode}
### Ranking Pages
| Rank | URL | DR | Est. Traffic | Content Angle |
|------|-----|----|-------------|---------------|
| 1 | example.com/page-one... | 72 | 8,200 | {angle from WebMCP title/H1, or "N/A — Ahrefs-only"} |
| 2 | competitor.com/article... | 65 | 5,100 | {angle} |
| 3 | site.com/guide... | 58 | 3,400 | {angle} |
| 4 | domain.com/resource... | 71 | 2,900 | N/A |
| 5 | blog.com/post... | 44 | 1,800 | N/A |
*URLs truncated to 60 characters. {If WebMCP used: "Page titles enriched via WebMCP." If not: "Ahrefs-only mode — page titles from SERP data where available."}*
### Key Insights
- **Top competitor:** {highest-DR domain} (DR {score}) — {what makes them dominant}
- **Content pattern:** {what type of content dominates — guides, tool pages, listicles, etc.}
- **Traffic concentration:** Top 3 results capture ~{X}% of estimated SERP traffic
- **Opportunity signal:** {any lower-DR pages ranking — weakness in the SERP}
### Competitive Summary
{2–3 sentence synthesis: what the SERP looks like, who dominates, what content
type wins, and whether there's a realistic path to ranking for this keyword.}
Error — Ahrefs MCP Not Available
If the Ahrefs MCP check fails, display this message and stop:
## Ahrefs MCP Not Available
The `/seo serp` command requires the Ahrefs MCP, which is not currently connected.
**What you can do:**
- Use `/seo audit <url>` for a full static SEO analysis without live SERP data
- Use `/seo technical <url>` for technical SEO issues without keyword data
**To connect Ahrefs MCP:**
- Ensure the Ahrefs MCP is registered at user scope in ~/.claude/mcp.json
- Verify with: cat ~/.claude/mcp.json | grep -i ahrefs
- Ahrefs MCP must be registered at user scope (not project scope) to work in subagents
Error — WebMCP Degraded Mode
If WebMCP is unavailable, display this note (non-blocking — continue execution):
## WebMCP Not Available — Running Ahrefs-Only Mode
The `/seo serp` command works best with both Ahrefs and WebMCP, but WebMCP
is not currently connected. Proceeding with Ahrefs data only.
**What's reduced:**
- Content angle analysis for top 3 URLs (page titles and H1s will not be fetched)
- SERP table will show "N/A" for Content Angle column
**To connect WebMCP:**
- Verify WebMCP registration status in ~/.claude/mcp.json