ahrefs

What this skill does

# Ahrefs SEO Tools

Query Ahrefs via their remote MCP server (Streamable HTTP transport). Joel has a **Standard plan** ($249/mo).

## Connection

**Endpoint:** `https://api.ahrefs.com/mcp/mcp`
**Auth:** Bearer token via `agent-secrets lease ahrefs_api_key`
**Transport:** Streamable HTTP (JSON-RPC over POST, NOT SSE)
**Config:** `~/.pi/agent/mcp.json` under `ahrefs` key

### Raw curl pattern (when MCP bridge isn't available)

```bash
AHREFS_KEY=$(agent-secrets lease ahrefs_api_key --ttl 4h --json 2>&1 | python3 -c "import sys,json; print(json.load(sys.stdin)['result']['value'])")

curl -s -X POST "https://api.ahrefs.com/mcp/mcp" \
  -H "Authorization: Bearer $AHREFS_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc":"2.0","id":1,"method":"tools/call",
    "params":{"name":"TOOL_NAME","arguments":{...}}
  }'
```

### MCP initialization handshake (required once per session)

```json
{"jsonrpc":"2.0","id":0,"method":"initialize","params":{
  "protocolVersion":"2025-03-26",
  "capabilities":{},
  "clientInfo":{"name":"pi","version":"1.0"}
}}
```

## Critical: Use `doc` tool first

Before calling any data tool for the first time, call the `doc` tool to get the real input schema:

```json
{"name":"doc","arguments":{"tool":"keywords-explorer-overview"}}
```

This returns the full schema with field names, types, filter syntax, and output columns. **The tool list schemas are summaries — `doc` gives the real contract.**

## API Units

Every call costs API units. The response includes cost info:
```json
{"apiUsageCosts":{"rows":10,"units-cost-row":21,"units-cost-total":210}}
```

- Monetary values (CPC, traffic_value, etc.) are in **USD cents**, not dollars. Divide by 100.
- `difficulty` costs 10 extra units per row when selected
- Standard plan has monthly unit limits — check with `subscription-info-limits-and-usage`

## Tool Categories

### Keywords Explorer (keyword research)

| Tool | Use for | Key required params |
|------|---------|-------------------|
| `keywords-explorer-overview` | Volume, KD, CPC for specific keywords | `select`, `country`, `keywords` (array) |
| `keywords-explorer-matching-terms` | Find keyword ideas matching seed terms | `select`, `country`, `keywords`, `limit`, `order_by` |
| `keywords-explorer-related-terms` | "Also rank for" and "also talk about" | `select`, `country`, `keywords` |
| `keywords-explorer-search-suggestions` | Autocomplete suggestions with metrics | `select`, `country`, `keywords` |
| `keywords-explorer-volume-history` | Historical volume trends | `country`, `keyword` (singular) |
| `keywords-explorer-volume-by-country` | Volume broken down by country | `keyword` (singular) |

**Common `select` fields:** `keyword`, `volume`, `difficulty`, `cpc`, `traffic_potential`, `global_volume`, `parent_topic`, `intents`, `clicks`, `cps`, `serp_features`

**Gotcha:** `keywords-explorer-overview` requires `keywords` as an array BUT returns empty results for broad terms — it only returns data for exact keyword matches in their DB. Use `matching-terms` or `search-suggestions` for discovery.

### Site Explorer (domain/URL analysis)

| Tool | Use for | Key required params |
|------|---------|-------------------|
| `site-explorer-metrics` | DR, traffic, keywords count | `target`, `date` |
| `site-explorer-organic-keywords` | What keywords a site ranks for | `select`, `target`, `date`, `country` |
| `site-explorer-organic-competitors` | Who competes in organic search | `select`, `target`, `country`, `date` |
| `site-explorer-top-pages` | Best pages by traffic | `select`, `target`, `date` |
| `site-explorer-all-backlinks` | Inbound link details | `select`, `target` |
| `site-explorer-referring-domains` | Domains linking to target | `select`, `target` |
| `site-explorer-domain-rating` | DR score | `target`, `date` |
| `site-explorer-domain-rating-history` | DR over time | `target`, `date_from` |
| `site-explorer-backlinks-stats` | Backlink summary stats | `target`, `date` |
| `site-explorer-anchors` | Anchor text analysis | `select`, `target` |
| `site-explorer-broken-backlinks` | Broken inbound links | `select`, `target` |
| `site-explorer-metrics-by-country` | Traffic by country | `target`, `date` |
| `site-explorer-metrics-history` | Historical traffic/keywords | `target`, `date_from` |

**`target`** = domain (`example.com`), URL (`https://example.com/page`), or path (`example.com/blog/*`)
**`mode`** = `exact` | `domain` | `subdomains` | `prefix`
**`date`** = `YYYY-MM-DD` (use recent date like today)

### SERP Analysis

| Tool | Use for | Key required params |
|------|---------|-------------------|
| `serp-overview` | Top results for a keyword | `select`, `country`, `keyword` |

### Batch Analysis

| Tool | Use for | Key required params |
|------|---------|-------------------|
| `batch-analysis` | Analyze multiple URLs/domains at once | `select`, `targets` (array) |

### Rank Tracker (requires project setup in Ahrefs UI)

Tools: `rank-tracker-overview`, `rank-tracker-competitors-*`, `rank-tracker-serp-overview`
All require `project_id` — get via `management-projects`.

### Site Audit (requires project setup in Ahrefs UI)

Tools: `site-audit-issues`, `site-audit-page-explorer`, `site-audit-page-content`, `site-audit-projects`

### Brand Radar (AI visibility monitoring)

Tools: `brand-radar-mentions-*`, `brand-radar-impressions-*`, `brand-radar-sov-*`, `brand-radar-ai-responses`, `brand-radar-cited-*`
Requires brand monitoring setup in Ahrefs UI.

### Web Analytics (requires Ahrefs analytics snippet)

All `web-analytics-*` tools require `project_id` from a Web Analytics project.

### Management

| Tool | Use for |
|------|---------|
| `management-projects` | List all projects |
| `management-project-keywords` | Keywords in a project |
| `management-project-competitors` | Competitors in a project |
| `management-locations` | Location IDs for targeting |
| `management-keyword-list-keywords` | Keywords from a saved list (**free, no units**) |
| `subscription-info-limits-and-usage` | Check remaining API units |

## Common Recipes

### Keyword research for a local service

```bash
# 1. Discover keywords
{"name":"keywords-explorer-matching-terms","arguments":{
  "keywords":["water damage restoration"],
  "select":"keyword,volume,difficulty,cpc,traffic_potential",
  "country":"us",
  "limit":20,
  "order_by":"volume:desc"
}}

# 2. Check specific local terms
{"name":"keywords-explorer-overview","arguments":{
  "keywords":["water damage restoration vancouver wa","water damage portland or"],
  "select":"keyword,volume,difficulty,cpc",
  "country":"us"
}}
```

### Competitor analysis

```bash
# 1. Get domain metrics
{"name":"site-explorer-metrics","arguments":{
  "target":"competitor.com",
  "date":"2026-03-11"
}}

# 2. See what they rank for
{"name":"site-explorer-organic-keywords","arguments":{
  "select":"keyword,position,volume,traffic,url",
  "target":"competitor.com",
  "date":"2026-03-11",
  "country":"us",
  "limit":20,
  "order_by":"traffic:desc"
}}

# 3. Find their competitors
{"name":"site-explorer-organic-competitors","arguments":{
  "select":"domain,common_keywords,keywords_unique_to_target",
  "target":"competitor.com",
  "country":"us",
  "date":"2026-03-11",
  "limit":10
}}
```

### Batch compare multiple domains

```bash
{"name":"batch-analysis","arguments":{
  "select":"target,domain_rating,organic_traffic,organic_keywords",
  "targets":["site1.com","site2.com","site3.com"],
  "country":"us"
}}
```

### Check API budget

```bash
{"name":"subscription-info-limits-and-usage","arguments":{}}
```

## Filter Syntax

The `where` parameter uses a JSON filter expression:

```json
{"field":"volume","is":["gte",100]}
```

Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `substring`, `isubstring`, `prefix`, `suffix`, `regex`

Boolean combinators: `and`, `or`, `not`

```json
{"and":[
  {"field":"volume","is":["gte",100]},
  {"field":"difficulty","is":["lte",30]}
]}
```

## MCP Config (co