# ahrefs-mcp

Unofficial community server, not affiliated with Ahrefs.

MCP server for the [Ahrefs API v3](https://docs.ahrefs.com/docs/api/reference/introduction). Gives Claude and any other MCP client live SEO data: keyword research, SERP analysis, backlink profiles, domain authority.

Built to be frugal with API units: narrow `select` lists per endpoint, in-memory response caching with per-endpoint TTLs (a cache hit costs 0 units), retries with backoff on 429/5xx. Monetary fields arrive from Ahrefs in USD cents and are normalized to dollars.

## Tools

16 tools across four groups.

| Group | Tool | What it returns |
|---|---|---|
| Keywords | `keyword-metrics` | Keyword ideas with volume, KD, CPC, traffic potential, intents |
| Keywords | `keyword-suggestions` | Autocomplete-style queries people actually type |
| Keywords | `related-keywords` | Terms top-ranking pages also rank for |
| Keywords | `keyword-volume-history` | Monthly volume trend and seasonality |
| Keywords | `keyword-volume-by-country` | Demand split by country |
| SERP | `serp-overview` | Top results with DR, UR, traffic, page type, AI overview presence |
| Site | `domain-rating` | DR and Ahrefs Rank |
| Site | `site-metrics` | Organic traffic, keywords, top-3 count, traffic value |
| Site | `site-metrics-history` | Monthly organic traffic trajectory |
| Site | `site-metrics-by-country` | Traffic split by country |
| Site | `backlinks-stats` | Live and all-time backlinks and referring domains |
| Site | `referring-domains` | Who links to a site, by authority |
| Site | `organic-keywords` | Keywords a domain ranks for, with positions |
| Site | `organic-competitors` | Competing domains with keyword overlap |
| Site | `top-pages` | Pages pulling the most traffic |
| Account | `subscription-usage` | API units used vs plan limit, never cached |

## Setup

Requires Node 18+ and an Ahrefs API key with API v3 access ([get one here](https://app.ahrefs.com/api-keys)).

```bash
git clone https://github.com/newilu/ahrefs-mcp.git
cd ahrefs-mcp
npm install
npm run build
```

### Claude Code

```bash
claude mcp add ahrefs -e AHREFS_API_KEY=your_key -- node /absolute/path/to/ahrefs-mcp/dist/index.js
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ahrefs": {
      "command": "node",
      "args": ["/absolute/path/to/ahrefs-mcp/dist/index.js"],
      "env": { "AHREFS_API_KEY": "your_key" }
    }
  }
}
```

## Example

> Pull the top 20 organic keywords for competitor.com in the US, then check SERP overview for the three with the lowest difficulty. Which ones have no site above DR 40 in the top 10?

The agent chains `organic-keywords` and `serp-overview` and answers with live data.

## Cost notes

Ahrefs bills per row and per selected field, so `limit` matters. Defaults here are deliberately small. Check `subscription-usage` before large batches. Cached responses (SERP 6h, keyword metrics 7d, site metrics 3d) are free.

## License

MIT