Updated May 21, 2026
TL;DR:
- This guide describes an approach to connect Claude Code to Ahrefs via the Model Context Protocol (MCP), giving your keyword research access to live search volume, difficulty scores, and SERP data without manual exports.
- The approach in this guide chains prompts to discover buyer-intent queries, filter commercial terms, cluster by semantic intent, and map to content pillars.
- AI-driven semantic clustering produces 19-27% accuracy improvements over representative baseline clustering methods, according to research on LLM-based categorical clustering, because models understand conceptual relationships that string matching misses.
- If your team lacks the bandwidth to run keyword strategy consistently, our Starter retainer handles the full content operations pipeline including keyword research, CITABLE-framework article production, and citation tracking.
Manual keyword research often follows a predictable pattern: pull a list from Ahrefs, filter by volume, guess at intent, group similar terms, and produce a spreadsheet nobody fully trusts. The bottleneck in most B2B SaaS content strategies is not a lack of keyword data. It is the operational drag of processing it by hand each cycle.
Claude Code, connected to Ahrefs via the Model Context Protocol, can remove that drag. You give it a seed keyword list and a set of chained prompts, and it returns clustered, intent-labeled, pillar-mapped keyword data ready for your editorial calendar. This guide covers the setup, the complete four-prompt workflow, and an illustrative example of a B2B SaaS team running it from raw list to prioritized content plan. This guide is one part of the broader Claude Code for SEO playbook.
Short answer: Connect Claude Code to Ahrefs using the Model Context Protocol (MCP) by running claude mcp add ahrefs in your terminal with the appropriate Ahrefs MCP server endpoint, then run four chained prompts to automate buyer-intent discovery, commercial filtering, semantic clustering, and pillar mapping. The workflow compresses a large keyword list into prioritized, intent-labeled clusters in a single session, streamlining manual spreadsheet work. You need an active Ahrefs subscription with API access enabled.
Why automate keyword research with Claude Code
The manual keyword research bottleneck
Manual keyword research takes experienced marketers through a slow sequence: export from Ahrefs, filter by volume, classify intent by eye, attempt grouping, and produce a spreadsheet that still carries subjective judgment in every cluster boundary. The process produces inconsistent results because intent classification varies between team members and changes depending on who has time to do it that week.
The problem compounds when you are operating across multiple buyer segments. At that volume, manual methods do not just slow content planning. They introduce enough noise that your editorial calendar ends up shaped by spreadsheet stamina rather than what the data says. For teams working on AI citation strategy, the cost is higher still. AI answer engines retrieve passages based on semantic relevance and topical authority. If your keyword clusters are misaligned, your content architecture may be misaligned as well, potentially affecting citation performance.
What Claude Code brings to keyword workflows
Claude Code is an agentic version of Claude that runs in your terminal and executes multi-step tasks autonomously. It supports discrete capabilities like file I/O and API calls that you can chain together so the agent completes a sequence of dependent steps without manual restarts between each one.
Connected to Ahrefs via MCP, Claude Code can act as a persistent research agent. The workflow described below retrieves live keyword data, applies intent classification logic, runs semantic grouping across hundreds of terms, and writes the output to a CSV. The approach aims to make a task that traditionally requires specialist knowledge more accessible to marketing generalists using structured prompts.
I cover the broader shift in how SEO workflows are changing in a recent new way of SEO video, and the Claude Code workflow sits at the operational core of that shift.
Traditional tools like Ahrefs and Semrush remain primary data sources for keyword research. The approach described here addresses the manual steps between pulling data and briefing writers, not the tools themselves. Use the Claude Code workflow when you have a seed list and need to scale it into a structured content plan. Use your standard tools for single-term research, competitive gap analysis, or quick volume checks where the overhead of a full agent session is not justified.
Generic LLMs without a live data connection may not be reliable for this. A Claude session without MCP could hallucinate keyword metrics or reason from training data that may be months out of date. The Ahrefs MCP integration, detailed below, is what makes the workflow produce accurate, current results.
Prerequisites and setup
Installing the Ahrefs MCP integration
The Model Context Protocol is a standardized interface that connects AI applications to external data systems. Think of it as a USB-C port for AI: a single standard where compatible tools connect directly, replacing the fragmented custom integrations that previously made LLM-to-data connections difficult to maintain at scale.
To add the Ahrefs MCP server to Claude Code, run this command in your terminal:
claude mcp add ahrefs
This registers the Ahrefs server with Claude Code using HTTP transport. After running it, confirm the registration with:
claude mcp list
You should see ahrefs listed in the output. The first time you call an Ahrefs tool in a session, you will see an authorization consent screen. Once approved, the connection appears in your account with a dedicated API key tagged with MCP scope. The MCP server uses your private Ahrefs API key to fetch data, and your data is only shared with the AI client configured on your local machine.
For a Semrush alternative, consult the MCP documentation for compatible endpoint configuration. The prompts in this guide are written for Ahrefs and need adapted column references for Semrush.
Authenticating your Ahrefs API access
You need an active Ahrefs subscription with API access enabled to use this workflow. Standard Ahrefs plans may not include API access by default, so check your plan level or contact Ahrefs to confirm. Once the MCP server is registered, Claude Code handles authentication on first use with a prompt that walks you through connecting your account.
One operational note: the Ahrefs API may enforce rate limits. For large keyword lists, structure your prompts to process in batches with pauses between them. The prompts below include batch handling instructions to help you stay within limits.
Preparing your seed keyword list
A typical starting point is 50-200 seed terms before running the workflow. Good sources include:
- Google Search Console: Export your top queries by impression for the past 90 days.
- Google autocomplete: Pull suggested completions for your primary category terms.
- Reddit and Quora: Extract the question phrasing buyers use in your product category.
- Competitor content gaps: Use Ahrefs' Content Gap tool or similar competitor analysis features to find terms competitors rank for that you do not.
Save the list as a plain text file or CSV. Claude Code can read it directly using ! cat keywords.txt to pipe the contents into your prompt.
Piping outputs between prompts: The workflow chains four prompts where each uses the previous output as input. You can pipe the seed list directly with ! cat keywords.txt in your first prompt. For subsequent prompts that reference CSV files like [keywords_expanded.csv], save the output from the previous step, then reference the file path in your next prompt or use ! cat keywords_expanded.csv to include the content inline.
The complete keyword research workflow
Workflow diagram: CLI to Ahrefs MCP to CSV
┌─────────────────────────┐
│ Seed keyword list │
│ (TXT or CSV input) │
└────────────┬────────────┘
│ ! cat keywords.txt | claude -p "[Prompt 1]"
▼
┌─────────────────────────┐
│ Claude Code (CLI) │
│ Agent session │
└────────────┬────────────┘
│ MCP call → Ahrefs API
▼
┌─────────────────────────┐
│ Ahrefs MCP Server │
│ Live volume, KD, │
│ SERP data returned │
└────────────┬────────────┘
│ Agent processes + classifies
▼
┌─────────────────────────┐
│ Intent classification │
│ + Semantic clustering │
│ (Prompts 2, 3, 4) │
└────────────┬────────────┘
│ Write output
▼
┌─────────────────────────┐
│ CSV output │
│ keyword, volume, KD, │
│ intent, cluster, │
│ pillar assignment │
└─────────────────────────┘
Step 1: Discover buyer-intent queries
This step aims to expand your seed list into buyer-intent queries. The prompt instructs Claude Code to synthesize autocomplete expansions and question-format variations, pull volume and keyword difficulty for each from Ahrefs, and flag terms where the phrasing suggests active vendor evaluation rather than early problem exploration.
This matters specifically for AEO content planning because AI answer engines may respond to natural question phrasing, not just head terms. A buyer asking "what is the best incident management platform for SaaS teams" signals something different from "incident management software," and those two signals need separate content responses.
Step 2: Filter commercial-intent keywords
Once you have an expanded list, the agent runs intent classification across four categories: informational, commercial, transactional, and navigational. Commercial and transactional terms typically map to content that earns pipeline. Informational terms typically map to content that builds topical authority and citation rate.
The filtering step also applies an opportunity matrix, scoring each term on the ratio of search volume to keyword difficulty. High-volume, low-difficulty commercial terms typically go to the top of the priority stack. Navigational terms, those targeting a specific brand by name, can be deprioritized rather than removed entirely, since they may matter in competitive contexts where your brand and a rival share similar naming. This resolves a persistent problem where blog posts targeting informational terms may rank well but not convert, while commercial pages lack the topical authority to compete. I cover this pattern in the AEO vs SEO full breakdown.
Step 3: Cluster keywords by search intent
Semantic clustering groups related terms by topic and buyer intent, producing a parent/child/sibling hierarchy that can map to your site architecture. Research on LLM-based categorical clustering confirms this approach produces 19-27% accuracy improvements over representative baseline clustering methods, because the model understands conceptual relationships that string matching misses.
In practice, a list of 1,000 keywords can compress significantly, with clusters ideally representing topics that warrant a pillar page and supporting spoke content rather than fifteen slightly different pages that split topical authority. Per the pillar-cluster model, each cluster typically maps to one pillar and a set of spokes targeting sub-questions, not a single standalone page. Our AI visibility tracker surfaces this fragmentation pattern in nearly every site we audit.
Step 4: Map clusters to content pillars
The final step organizes clusters into a pillar/spoke architecture, assigning each cluster to the appropriate funnel stage and the pillar page it should link to or support. The goal is an output that may include a recommended production sequence showing which piece to write first (typically the pillar), which spokes support it, and the internal linking chain that signals topical authority to both Google and AI answer engines.
This is where keyword research connects directly to the CITABLE framework. Each cluster becomes an intent architecture input. The CITABLE framework is our seven-component system for structuring content to maximize AI citation rates: Clear entity and structure, Intent architecture, Third-party validation, Answer grounding, Block-structured for RAG, Latest and consistent, and Entity graph and schema. Intent architecture means answering not just the primary query but the adjacent questions the buyer may have next.
Four copy-paste prompts for Claude Code
Prompt 1: Buyer-intent query discovery
You are an SEO strategist for a B2B SaaS company.
Using the Ahrefs MCP, expand the following seed keywords into a
comprehensive buyer-intent query list. For each seed term:
1. Generate question-format variations buyers would type
2. Retrieve search volume and keyword difficulty via Ahrefs
3. Flag terms where the query phrasing indicates active vendor
evaluation (e.g., "best X for Y", "X vs Y", "how to choose X")
4. Process keywords in manageable batches with pauses between batches
to respect API rate limits (60 requests per minute)
Seed keywords: [PASTE YOUR SEED LIST HERE]
Suggested output format: CSV with columns: original_seed, expanded_query,
monthly_volume, keyword_difficulty, buyer_stage_flag
Why this works: The buyer-stage flag separates evaluation-phase queries from awareness-phase ones early in the process, so your commercial content gets prioritized before the clustering step.
Prompt 2: Commercial-intent filtering
You are an SEO strategist applying an opportunity matrix to a
keyword list.
Using the keyword data provided, filter and score this list by
commercial value:
1. Classify each term: Informational, Commercial, Transactional,
or Navigational
2. Score each commercial/transactional term using a composite
opportunity score that balances volume, difficulty, and relevance
3. Deprioritize navigational terms; retainterms. Retain them in output but
flag as low priority unless competitive brand context applies
4. Flag informational terms as "authority-building" rather than
pipeline terms
5. Sort commercial terms by opportunity score descending
Input file: [keywords_expanded.csv]
Suggested output format: CSV with columns: keyword, monthly_volume,
keyword_difficulty, intent_category, opportunity_score,
pipeline_priority (High/Medium/Low)
Why this works: The opportunity score gives you a single sortable number that accounts for both demand and competition, removing the subjective debate about which terms to prioritize.
Prompt 3: Intent-based clustering
You are a semantic SEO specialist. Group the following commercial
and informational keywords into semantic clusters.
Rules:
1. Each cluster should represent one distinct topic or buyer question
2. Assign a parent keyword (highest volume, clearest intent)
per cluster
3. Assign child keywords that are close variants of the parent
4. Assign sibling keywords that share the parent topic but differ
in buyer stage or angle
5. Each cluster represents a topic area for a pillar page plus
supporting spoke content - not a single standalone page
Input file: [keywords_filtered.csv]
Suggested output format: CSV with columns: cluster_id, cluster_name,
parent_keyword, keyword, keyword_type (parent/child/sibling),
monthly_volume, keyword_difficulty, intent_category
Why this works: The parent/child/sibling hierarchy maps directly to the pillar-and-spoke architecture that signals topical authority to both Google and AI answer engines. Clusters that stay too granular recreate the fragmentation problem you started with.
Prompt 4: Content pillar mapping
You are a content strategist for a B2B SaaS company.
Using the semantic clusters provided, build a content pillar
hierarchy:
1. Identify 3-5 pillar topics that cover the broadest,
highest-volume commercial themes
2. Assign each cluster as a spoke under the most relevant pillar
3. Recommend the funnel stage for each piece:
Top of Funnel / TOFU (awareness), Middle of Funnel / MOFU (consideration),
Bottom of Funnel / BOFU (decision)
4. Assign a production priority (1 = produce first) based on:
- Cluster opportunity score
- Funnel stage (some strategists prioritize BOFU for immediate
business results, while others start with TOFU for broader reach)
- Whether a pillar page exists or needs to be created first
Input file: [keywords_clustered.csv]
Suggested output format: CSV with columns: pillar_topic, spoke_cluster,
content_title_suggestion, target_keyword, funnel_stage,
production_priority, estimated_word_count
Why this works: Some content strategists prioritize BOFU production first to address immediate business results, while traditional approaches start with TOFU for broader reach. The key is addressing the most common B2B SaaS content failure mode, where teams build extensive informational content but have thin coverage at the decision stage where buyers are actively evaluating vendors.
Illustrative workflow: B2B SaaS marketing team
The starting keyword universe
An illustrative B2B SaaS company in the HR tech space starts with a keyword export from Ahrefs covering everything from broad category terms to long-tail question formats to competitor comparisons. The list is flat, with no intent labels, no grouping, and significant overlap across terms that are effectively the same query phrased slightly differently.
The marketing team has been manually sorting a similar list each quarter. The output varied depending on who was doing it, and the clusters they produced reflected whoever had done the spreadsheet work that month rather than a consistent methodology.
Running the four-prompt sequence
They run the four prompts as a chained sequence in one Claude Code session, with each output piped as input to the next. Following the prompt instructions, the workflow flags navigational terms and deprioritizes them, identifies distinct buyer segments the team has been treating as one audience, and surfaces question-format queries with meaningful volume that were missing from the original seed list.
Output: clustered keywords and pillar assignments
The keywords compress into semantic clusters organized across a small set of pillar topics. Each cluster includes a production priority score, a suggested content title, and a funnel stage label. The team can identify their highest-priority BOFU clusters and move them directly into the next sprint, a set that would otherwise be buried in the original flat list with no clear prioritization signal.
This is the same semantic cluster logic we use to build the topical foundation for the CITABLE framework in client engagements. Tom Wentworth, CMO at incident.io, put the impact of this kind of structured approach directly:
"Before Discovered Labs, we were using homegrown LLM prompts, without a clear strategy for what to optimize for or exactly how best to structure content." - Tom Wentworth, CMO at incident.io
Exporting and using your keyword clusters
From CSV to content calendar
Following Prompt 4, Claude Code should write the final output to a CSV with columns that might include: pillar_topic, spoke_cluster, content_title_suggestion, target_keyword, funnel_stage, and production_priority. The goal is for each row to represent one piece of content, not one keyword, which is a key structural difference from a raw Ahrefs export.
Consider sorting the CSV by production_priority ascending before import into your editorial calendar tool. Your highest-priority content comes first, and within each funnel stage, the opportunity score should sort by volume-to-difficulty ratio. Assign content titles to writers with the target_keyword and funnel_stage columns so they have the intent context before they start.
For teams building out full content operations including briefing, writing, and CITABLE-framework optimization, our Starter retainer handles this entire pipeline at up to 20 articles per month. The keyword cluster map from this workflow can support our brief generation process.
Prioritizing clusters by search volume and intent
Two signals can override the automated priority score when you apply human review. First, if a cluster addresses a question your sales team hears on calls, consider moving it up regardless of volume. Second, if a competitor has a strong piece targeting the cluster's parent keyword, earlier prioritization may be warranted, because thin coverage in a high-competition cluster may hurt your citation rate on adjacent terms.
Our AI visibility tracker shows precisely which competitor content is being cited on your priority buyer queries, making these prioritization decisions more precise than volume-and-difficulty scores alone. The AEO test bed guide explains why measurement rigor at this stage matters for getting signal rather than noise from your visibility data.
Common issues and troubleshooting
API rate limits and batch processing
The Ahrefs API allows 60 requests per minute at a base cost of 50 units per call. For large keyword lists, Prompt 1 may hit this limit without batch handling. The prompt above includes a 60-second pause between batches of 500. If you see an HTTP 429 error, apply exponential backoff: start with a 2-second wait, double it with each retry (4 seconds, 8 seconds, 16 seconds), and reduce your batch size. Fixed-interval pauses may be less effective than escalating delays when the API is under load.
For very large lists, consider splitting your seed input into two files and running the sequence twice, then merging the cluster outputs before running Prompt 4. The pillar mapping step may work better with a unified cluster list, so the merge can be worth doing before that final pass.
Handling ambiguous search intent
Add a clarifying instruction to Prompt 2 when you see misclassification patterns. A common issue is commercial investigation queries being tagged as informational. Terms like "X software review" or "compare X platforms" typically signal active evaluation, not passive research. Add this line to Prompt 2: "Treat review, comparison, and alternative queries as Commercial intent regardless of phrasing."
The AI slop SEO guide covers a related failure mode where automated content generation on a poorly clustered keyword map may produce topically thin pages that neither rank nor earn citations.
When manual review is still necessary
Automated clustering handles volume well but may miss domain-specific nuance your product or sales team recognizes immediately. Always review the clusters designated as pillar pages before production starts. A model trained on general web text may group terms that are semantically similar in general language but represent distinct buying segments in your specific market. Your product or sales lead can work through the pillar-level clusters with the CSV in front of them, and getting the pillar structure right before production starts may be far more efficient than restructuring it after articles have been written to the wrong architecture.
I walk through the content structure decisions that drive citation rate in a B2B SaaS case study showing how one brand reached #1 in ChatGPT, which is worth watching before your next content planning cycle.
If your team wants this workflow built into a full content operations system with citation tracking, CITABLE-framework production, and AI visibility measurement, book a call and we will tell you honestly whether we are a fit.
FAQs
Do I need an Ahrefs subscription to use this workflow?
Yes, you need an active Ahrefs subscription with API access enabled, as the MCP integration calls the Ahrefs API directly to retrieve live keyword metrics. Standard Ahrefs plans do not include API access by default, so confirm your plan level or contact Ahrefs to enable it before setup.
Can I use this workflow with Semrush instead of Ahrefs?
Yes, Semrush has a compatible MCP integration you can add with claude mcp add semrush https://mcp.semrush.com/v1/mcp -t http. The four prompts need adjusted column names to match Semrush's data schema, but the logic and chaining sequence stay the same.
How often should I refresh my keyword clusters?
Run a full refresh quarterly. Between cycles, consider using Prompt 1 alone on a shorter seed list to surface new buyer-intent queries that have emerged, which may be particularly relevant in fast-moving B2B SaaS categories where buyer language shifts as product categories mature.
Does this workflow apply to local or e-commerce keywords?
The intent classification and clustering logic can be adapted to various keyword sets, though industry-specific variations often require separate clustering strategies. Prompt 4's pillar mapping examples use B2B SaaS buyer journeys with Top of Funnel (TOFU) / Middle of Funnel (MOFU) / Bottom of Funnel (BOFU) stages. For local or e-commerce use cases, you would modify the funnel stage taxonomy in Prompt 4 to match your purchase cycle.
The full picture of how keyword architecture connects to AI search performance across web search, citations, and training data surfaces is covered in the SEO vs AEO explainer video, which is useful context before your next quarterly content planning session.
Automated keyword research removes the operational drag slowing your content planning and the subjective judgment contaminating what should be a data-driven process. The four-prompt Claude Code workflow above gives your team the same output as a dedicated specialist running manual analysis, with reproducible results across every cycle.
Key terms glossary
- Model Context Protocol (MCP): A standardized interface that connects AI applications like Claude Code to external data systems such as Ahrefs, enabling live keyword data retrieval directly within an agent session.
- Keyword difficulty (KD): An Ahrefs metric that scores how competitive a keyword is to rank for on a 0-100 scale. Used alongside search volume to calculate opportunity score and prioritize which terms to target.
- Semantic clustering: The process of grouping keywords by conceptual meaning and buyer intent rather than string similarity. Produces a parent/child/sibling hierarchy that maps directly to your site architecture.
- Pillar/spoke architecture: A content structure where a broad pillar page covers a core topic and spoke pages target supporting sub-questions. Internal links between them signal topical authority to both Google and AI answer engines.
- Intent classification: The categorization of keywords into four types: informational, commercial, transactional, and navigational. Used to separate pipeline-driving terms from authority-building ones before production prioritization.
- Opportunity score: A composite metric that balances search volume, keyword difficulty, and relevance to rank commercial keywords by their value relative to the competition required to rank for them.
