Ahrefs MCP: a keyword research API inside Claude, setup and what it costs in API units

We planned this entire guide section with the Ahrefs MCP server: the keyword clusters, the difficulty filters, the traffic-potential rankings. It is the fastest way we know to go from "what should we write" to a prioritised list, and it works from inside Claude Code so the research lands next to the content. This guide covers setup, the tools, a workflow that works, and the part nobody tells you about: API units.

Setup

The server is remote and official. In Claude Code:

claude mcp add ahrefs https://api.ahrefs.com/mcp/mcp -t http

Start a session, run /mcp, choose Ahrefs and complete the login in the browser. In Claude Desktop, add it as a custom connector with the same URL. In Cursor, add it to mcp.json with the url field. General instructions are in Claude Code, Cursor and Claude Desktop.

You need an Ahrefs plan that includes API access. The server tells you if you do not.

What it exposes

The server mirrors Ahrefs API v3, which is large. The tools that matter for content and SEO work:

• Keywords Explorer: matching terms, related terms, search suggestions, overview, volume by country and history.
• Site Explorer: organic keywords, top pages, referring domains, backlinks, domain rating, competitors, and history for all of them.
• SERP overview: who ranks for a keyword, with domain rating, traffic and page type.
• Rank Tracker: your tracked keywords and competitors.
• Site Audit: crawl issues and page data.
• Brand Radar: mentions, citations and share of voice in AI answers, which is the closest thing to a metric for SEO for AI search.

Every tool has a doc companion that returns its schema, and the server asks you to call it before first use. Results include a render_with hint; the server expects the client to render tables rather than paste raw JSON.

MCP or calling the keyword research API directly

Ahrefs API v3 is a keyword research API in its own right, and plenty of teams call it from scripts: a nightly job that pulls volumes for a keyword list, a dashboard that tracks rankings. The MCP server does not replace that. It changes who writes the queries.

The two work well together. Use MCP to find out which questions are worth asking, then hard-code the ones you ask every week. The best MCP servers for marketing and SEO guide covers the other data sources that sit next to it.

A workflow that works

The sequence we use, which is also documented in our own repository's instructions for future sessions:

1. Seed from the offering. List 10 to 15 terms per theme from your positioning, not from what the tools suggest.
2. Query per market, questions mode and phrase mode, with a filter such as volume above 150 and difficulty below 25.
3. Rank by traffic potential over difficulty, not by volume. A 400-a-month query whose top page pulls 50 000 visits beats a 5 000-a-month query whose top page pulls 250.
4. Check what you already rank for with Site Explorer so you do not cannibalise.
5. Check the SERP for each target: if the top ten are all DR 70 news sites, move on.
6. Write the cluster, pillar first, then the questions.

Packaged as a skill, that becomes a repeatable content-planning routine any marketer on the team can run.

API units

Ahrefs bills the API in units, separately from seats. Each MCP call reports its cost, for example:

rows: 100, units-cost-row: 54, units-cost-total: 5400

The cost scales with rows returned and columns selected; difficulty and traffic-potential columns cost more than volume. Practical rules: select only the columns you need, use limit and where filters aggressively, and prefer one query with a good filter over ten exploratory ones. A planning session for a content cluster runs to tens of thousands of units; check your plan's monthly allowance before letting an agent loop.

Running it from Europe

Keyword data is aggregated market data, not personal data, so a keyword research API is rarely a GDPR problem in itself. The exposure is everything around it. A real research session mixes Ahrefs with your own Search Console queries, your Analytics conversions and your positioning documents, and all of it passes through the model. For a European team the question to answer is where that model runs and who can see the log, not where Ahrefs stores its keyword index.

For a team

An Ahrefs login through MCP grants the whole API allowance to whoever holds the session. In a team, that belongs behind a gateway with per-user access and a log of who spent the units on what. Walma AI Hub runs Ahrefs alongside Search Console, Google Analytics and Google Ads in the customer's own EU region, which is how our own marketing runs. Book a walkthrough if you want the same.

The full set of marketing connections is on AI for marketing.