# Ahrefs MCP

Use Ahrefs when the user explicitly asks for Ahrefs data, when DR/UR weighting matters, or when the task needs `gsc-keywords` (Ahrefs is the only SEO MCP that exposes a Google Search Console integration directly).

Namespace: `mcp__ahrefs__*` (Claude Desktop) / `mcp__claude_ai_Ahrefs__*` (Claude.ai). Same backend.

## Keyword endpoints

- `keywords-explorer-overview` — volume, CPC, KD, parent topic
- `keywords-explorer-matching-terms` — phrase-match expansion
- `keywords-explorer-related-terms` — related ideas
- `keywords-explorer-search-suggestions` — autocomplete-style suggestions
- `keywords-explorer-volume-by-country` — country breakdown for one keyword
- `keywords-explorer-volume-history` — historical search volume

## GSC integration (Ahrefs-only)

- `gsc-keywords` — keywords the user's verified site actually ranks for (impressions, clicks, CTR, position)
- `gsc-keyword-history` — historical performance of a query

GSC endpoints require the Ahrefs project to be connected to the GSC property. Confirm with the user that the project exists in their Ahrefs workspace before relying on these.

## Common parameters

- `country` — `us`, `kr`, `jp`, etc. (lowercase ISO-2)
- `keyword` — the seed term
- `limit` — usually 30–100

## Examples

**Quick overview:**
```
mcp__ahrefs__keywords-explorer-overview(keyword="enterprise CRM", country="us")
```

**Related terms in Korean:**
```
mcp__ahrefs__keywords-explorer-related-terms(keyword="신라호텔", country="kr", limit=50)
```

**GSC first-party queries:**
```
mcp__ahrefs__gsc-keywords(project_id="<ahrefs project id>", limit=100)
```

## When NOT to use Ahrefs for this skill

- Default keyword volume / matching terms — Semrush is the project default; only switch on explicit request.
- Bulk Korean expansion — `our keywords ideas --location 2410` is usually cheaper.
- Entity / Knowledge Graph seeding — `mcp__ourseo__search_knowledge_graph`.

## Reference

Always check `mcp__ahrefs__doc` once per session before first call — it documents current parameter shapes and may have changed.
