# How to connect Ahrefs to Hermes Agent (paste one key, 40 tools)

> Connect Ahrefs to Hermes with ClawLink: paste your Ahrefs key once and 40 tools work from chat. No MCP server to run, nothing stored on your machine.

Web version: https://claw-link.dev/hermes/ahrefs

Most guides for giving Hermes Agent Ahrefs access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Ahrefs setup: pair once in the browser and your always-on Hermes agent can act on Ahrefs for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Ahrefs.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Ahrefs** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect ahrefs  # connect Ahrefs (browser OAuth)
npx -y @useclawlink/cli actions ahrefs  # list available actions
npx -y @useclawlink/cli run ahrefs <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Ahrefs in the [ClawLink dashboard](https://claw-link.dev/dashboard) — paste your Ahrefs API key once.

Verify the connection by asking Hermes:

> Use ahrefs_retrieve_organic_keywords for \<domain> and ahrefs_domain_rating_for_site_explorer for the same domain. Tell me the top 10 keywords by volume and the domain rating. Do not walk backlinks yet.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Ahrefs is connected in the dashboard, that agent calls the same 40 Ahrefs tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Ahrefs MCP for Hermes

Looking for a Ahrefs MCP server for Hermes Agent? ClawLink connects Ahrefs to Hermes Agent and exposes 40 Ahrefs tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Ahrefs integration](https://claw-link.dev/openclaw/ahrefs) works the same way.

Two things Google teaches that this page has never answered head-on. First, the key a guide means by "Ahrefs MCP" is usually not the key you generate in Ahrefs: the official hosted MCP endpoint wants its own dedicated key, and a standard v3 API key fails its tool router. The key this page wants is the normal Ahrefs API key, pasted once into the hosted setup page, held server-side, and every Ahrefs tool below runs on it. Second, the "without an API key" query is currently answered by Ahrefs' own agent product, Agent A, which is the agent instead of letting your agent be the agent. This page is the reverse: Hermes Agent (the CLI agent that pairs through `hermes plugins install`, not Nous Research's Hermes model) stays your agent, and it gets the full Ahrefs API under your account.

## What the Hermes Agent Ahrefs integration can do

40 Ahrefs tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 40.

### 30 of 40 Ahrefs tools for Hermes

| Tool | What it does |
|---|---|
| **Backlinks stats retrieval** `ahrefs_backlinks_stats_retrieval` | Get backlink statistics |
| **Domain rating for site explorer** `ahrefs_domain_rating_for_site_explorer` | Get domain rating from Ahrefs |
| **Explore keyword volume by country** `ahrefs_explore_keyword_volume_by_country` | Explore keyword volume by country |
| **Explore keywords overview** `ahrefs_explore_keywords_overview` | Get keyword overview from Ahrefs |
| **Explore matching terms for keywords** `ahrefs_explore_matching_terms_for_keywords` | Find matching terms for a keyword |
| **Fetch all backlinks** `ahrefs_fetch_all_backlinks` | List all backlinks from Ahrefs |
| **Fetch broken backlinks data** `ahrefs_fetch_broken_backlinks_data` | List broken backlinks from Ahrefs |
| **Fetch competitors overview** `ahrefs_fetch_competitors_overview` | Get organic competitors overview |
| **Fetch rank tracker overview** `ahrefs_fetch_rank_tracker_overview` | Get rank tracker overview |
| **Fetch site explorer referring domains** `ahrefs_fetch_site_explorer_referring_domains` | List referring domains from Ahrefs |
| **Get serp overview** `ahrefs_get_serp_overview` | Get SERP overview from Ahrefs |
| **Get site audit projects** `ahrefs_get_site_audit_projects` | List Ahrefs site audit projects |
| **Pages by traffic overview** `ahrefs_pages_by_traffic_overview` | Get pages by traffic overview |
| **Retrieve organic competitors** `ahrefs_retrieve_organic_competitors` | List organic competitors for a domain |
| **Retrieve organic keywords** `ahrefs_retrieve_organic_keywords` | List organic keywords for a domain |
| **Batch URL analysis** `ahrefs_batch_url_analysis` | Performs a batch analysis on multiple URLs or domains using Ahrefs' powerful SEO metrics |
| **Domain rating history** `ahrefs_domain_rating_history` | Retrieves the historical Domain Rating (DR) data for a specified domain over time |
| **Explore linked domains of a site** `ahrefs_explore_linked_domains_of_a_site` | Retrieves a list of external domains that the specified target website or URL links to, using |
| **Fetch total search volume history** `ahrefs_fetch_total_search_volume_history` | Retrieves the historical total search volume data for specified keywords using Ahrefs' Site |
| **Get site explorer country metrics** `ahrefs_get_site_explorer_country_metrics` | Retrieves country-specific Site Explorer metrics for a given website from Ahrefs |
| **Get site explorer linked anchors external** `ahrefs_get_site_explorer_linked_anchors_external` | The site-explorer-linked-anchors-external endpoint retrieves data about external anchor texts |
| **Get URL rating history** `ahrefs_get_url_rating_history` | Retrieves the historical URL Rating data for a specified URL over time |
| **Linked anchors explorer** `ahrefs_linked_anchors_explorer` | Retrieves information about internal linked anchors for a specified website using the Ahrefs API |
| **List best by external links** `ahrefs_list_best_by_external_links` | The 'get_best_by_external_links' endpoint retrieves a list of pages from a specified website |
| **Retrieve anchor data** `ahrefs_retrieve_anchor_data` | Retrieves anchor text data for a specified website or URL using Ahrefs' Site Explorer tool |
| **Retrieve best by internal links** `ahrefs_retrieve_best_by_internal_links` | Retrieves data on the best-performing internal links within a specified website using Ahrefs' |
| **Retrieve crawler ip ranges** `ahrefs_retrieve_crawler_ip_ranges` | Retrieves the list of IP address ranges used by Ahrefs' web crawler (AhrefsBot) |
| **Retrieve outlinks stats** `ahrefs_retrieve_outlinks_stats` | Retrieves comprehensive statistics about outgoing links (outlinks) from a specified website |
| **Retrieve paid pages data** `ahrefs_retrieve_paid_pages_data` | Retrieves information about paid pages (PPC advertising) for a specified website using Ahrefs' |
| **Retrieve public crawler ips** `ahrefs_retrieve_public_crawler_ips` | Retrieves a list of IP addresses currently used by AhrefsBot, Ahrefs' web crawler |

## Example prompts

**Audit a competitor**

> Use ahrefs_retrieve_organic_keywords for \<domain> and ahrefs_domain_rating_for_site_explorer for the same domain. Tell me the top 10 keywords by volume and the domain rating. Do not walk backlinks yet.

**Find broken link opportunities**

> Call ahrefs_fetch_broken_backlinks_data for \<domain> and list the broken backlinks with their source pages, sorted by domain rating of the source. Keep it to the first page of results.

**Check the SERP for a keyword**

> Run ahrefs_get_serp_overview for \<keyword> in the US database and tell me who ranks in the top 10 and which results are ads.

**Keyword research**

> Use ahrefs_explore_keywords_overview for \<seed keyword> and ahrefs_explore_matching_terms_for_keywords for the same seed. Give me a table of the 15 best matching terms by volume with their difficulty.

## How the Ahrefs tools behave

Details that decide whether an Ahrefs prompt is a quick answer or a long enumeration.

- **Every tool takes a target and a database.** Domains, URLs, and keywords are passed per call, and the database argument (US by default) decides the market the numbers describe. An id or keyword from one market fails like a typo in another.
- **The inventory tools page.** `ahrefs_fetch_all_backlinks` and `ahrefs_retrieve_organic_keywords` walk result pages one call at a time, so a large site means many requests. Name a page limit in the prompt.
- **Ids come from the explorer tools, not from memory.** `ahrefs_retrieve_organic_keywords` and `ahrefs_fetch_site_explorer_referring_domains` are where targets for follow-up calls come from; an id invented from documentation fails like a permission error.
- **Competitors are data, not opinions.** `ahrefs_fetch_competitors_overview` and `ahrefs_retrieve_organic_competitors` both answer "who competes with us", but from different angles: one is the competitor summary report, the other the organic keyword overlap list. Say which you want.
- **Rank tracker and site audit are project-shaped.** `ahrefs_fetch_rank_tracker_overview` and `ahrefs_get_site_audit_projects` read from Ahrefs projects that exist in the connected account; with no projects configured they return empty, not errors.
- **Units are consumed per call.** Every request draws from the account's API unit allowance, so a prompt that asks for everything at once is the expensive shape. One target, one endpoint, one page.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Ahrefs working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Credential handling** | Collect, validate, store, and rotate the Ahrefs API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected Ahrefs account becomes available to the agent without you building credential management. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Ahrefs. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Ahrefs actions to the runtime in a format your agent can reliably use. | 40 tools for Ahrefs are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Ahrefs to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Ahrefs in the browser, and the 40 tools above work from chat. There is no SDK and no config file, and the Ahrefs key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Ahrefs
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect Ahrefs from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Ahrefs tools
Ahrefs tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Ahrefs call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Ahrefs returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### Ahrefs returns 403 "insufficient permissions" although the account shows as connected
Four causes are in play on this provider, and two of them predate ClawLink. The causes search results teach are plan tier, key scope, and exhausted API units: the endpoint needs a plan that includes it, the key must carry the scope for that endpoint, and an account that has spent its unit allowance is refused regardless of the key. The hosted-flow causes are the ones this page's card already names: the connected Ahrefs user cannot see the target (workspace and plan decide what a user can read), and a placeholder value such as YOUR_DOMAIN reaching the API as a literal argument fails like a permission error. There is also the MCP-key confusion: a key generated for the official MCP endpoint is refused by v3 API calls, so if a key was created under the MCP instructions, pasting it here fails until a normal v3 key is used.

Ask the agent to diagnose it:

```text
Call ahrefs_explore_keywords_overview with one real keyword and ahrefs_get_site_audit_projects, and quote the exact error text from each. Do not retry the failed call yet.
```

### Ahrefs starts returning 429 or the agent stalls partway through a domain audit
Ahrefs rate-limits the API and prices it in units, and an agent walking a large site is the traffic shape that meets both: backlinks, then referring domains, then anchors, one call at a time. The response is not to retry immediately but to narrow the work. Ask for one target, one endpoint family, and a page count before the sweep starts, so a request that would take sixty calls becomes six. If the account's monthly units are the constraint, that is visible in the Ahrefs dashboard and no retry changes it. The rate card here deliberately carries no threshold numbers because the limits move and are documented on Ahrefs' side.

Ask the agent to diagnose it:

```text
Tell me how many Ahrefs calls you have made in the last minute and what you were enumerating. Quote the error text from the last response. Do not call Ahrefs again until I reply.
```

### Ahrefs tools are missing, or one tool name is not found
Two failures share this symptom. If no Ahrefs tools appear at all, the connection or pairing is incomplete: confirm the plugin was installed with --enable, that both `hermes clawlink begin` and `hermes clawlink finish` ran, and that Ahrefs shows as connected in the dashboard. If most tools work and one name fails, the name is wrong rather than missing and the error lists the closest real ones. There is also a first-call case unique to this setup: schemas load on demand, so the opening Ahrefs call in a fresh session can arrive before the catalog and needs one retry. What does not apply is the usual advice for this symptom, which blames the local MCP server that Ahrefs discontinued and the client-side tool cache; there is no local server here.

Ask the agent to diagnose it:

```text
List the Ahrefs tools you actually have access to. If there are none, say so plainly and tell me whether the connection shows as connected. Do not guess tool names from documentation.
```

### API key setup works but results look incomplete
Double-check that the API key for Ahrefs has the right scopes or account access. A valid key can still be too limited for some reads or writes.

### Is there a Hermes Agent Ahrefs integration?
Yes. ClawLink is the fastest way to connect Hermes to Ahrefs: link your Ahrefs account once in the browser and Hermes Agent can call the Ahrefs API through 40 ready-made tools — no custom code or token handling.

### How do I connect Ahrefs to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect Ahrefs in the dashboard and Hermes can use it from the next message — no config files, and the Ahrefs key you paste is stored server-side instead of in your environment.

### How long does it take to connect Ahrefs to Hermes Agent?
About two minutes. Sign in, click Connect next to Ahrefs in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring Ahrefs up myself?
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Ahrefs working from chat.

### Which key does this need, and why does the official MCP want a different one?
A normal Ahrefs API key from Ahrefs settings, entered once on the hosted setup page. The distinction matters because search results for Ahrefs MCP teach a dedicated key for the official MCP endpoint, and the two are not interchangeable: a standard v3 API key fails that endpoint's tool router. Here there is no MCP endpoint to satisfy. The one key you paste is the v3 key, the agent calls the 40 tools below through it, and rotating it in Ahrefs means updating a single place in the dashboard.

### How is this different from Ahrefs Agent A?
Agent A is Ahrefs' own agent: you ask it questions inside Ahrefs, and it answers without you handling a key. ClawLink is the opposite arrangement. Hermes is your agent, it lives in your terminal and chat, and it reaches the same Ahrefs data under your account. The tradeoff Ahrefs itself documents for agent setups is that behind the scenes the account permissions still decide what is visible, which is true here too: the agent sees what your Ahrefs user and plan can see. If you already work inside Ahrefs and never leave it, Agent A is fine. If your agent workflow lives in Hermes, this is the way the data gets there.

### What can the agent do in Ahrefs?
The read side of Ahrefs: backlinks and broken backlinks, organic keywords and competitors for a domain, SERP overviews, rank tracker data, site audit projects, domain rating and its history, URL rating, anchor texts, linked and outbound domains, country-level site explorer metrics, and keyword volume and matching-term research. There are no write tools in the set, so nothing in Ahrefs can be changed by the agent, which is the right shape for an SEO research surface.

### Does the agent burn my Ahrefs API units?
Yes, and it is worth knowing before a long audit prompt. Ahrefs bills the API by units consumed per request, and every call the agent makes draws from the same account allowance your own API calls would. The practical guard is to name one target at a time and say what you want before the agent enumerates, because walking every backlink or every organic keyword of a big domain is many requests. A 429 response is Ahrefs enforcing its rate window or the account's unit state, not a ClawLink failure.

### Hermes paired but still can't use Ahrefs
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [Hermes PostHog integration](https://claw-link.dev/hermes/posthog) — Track user behavior and feature flags
- [DataforSEO](https://claw-link.dev/hermes/dataforseo) — SEO data APIs for keywords, SERP, and site audits
- [Hermes Metabase integration](https://claw-link.dev/hermes/metabase) — Metabase is an open-source business intelligence tool that lets you ask questions about your data and visualize answers as charts, graphs, and dashboards.