This is not an Ahrefs problem. Ahrefs has an official Claude connector with a full OAuth flow — workspace selection, consent screen, the works. The Ahrefs MCP server itself is well-built and works correctly when called directly. The problem is that the OAuth integration between Claude.ai and Ahrefs is unreliable. It works for some users, breaks for others, and can stop working after initially connecting. Ahrefs says it's Claude's issue. Anthropic hasn't fixed it. Neither side is resolving the underlying problem. This project is a workaround until one of them does.
A Cloudflare Worker that proxies requests to the Ahrefs remote MCP server, injecting your MCP key so Claude.ai (and any other MCP client) can reliably access all 95+ Ahrefs tools.
Works on all paid Ahrefs plans (Lite, Standard, Advanced, Enterprise). No Enterprise subscription required.
Ahrefs has a remote MCP server at api.ahrefs.com/mcp/mcp — 95+ tools covering Site Explorer, Keywords Explorer, Brand Radar, Site Audit, Rank Tracker, batch analysis, and more.
Ahrefs is a listed Claude connector. You can add it in Claude.ai under Settings → Integrations, authorize via OAuth, and start using it. When it works, it's great. But for many users, the OAuth flow fails:
"There was an error connecting to the MCP server. Please check your server URL and make sure your server handles auth correctly."
The Ahrefs MCP server supports OAuth and has a working implementation. Claude.ai has an approved Ahrefs connector that uses it. The issue is in the reliability of the OAuth handshake between the two systems. The most likely failure points:
- Token refresh — OAuth access tokens expire. When Claude.ai attempts to refresh an expired token and the refresh fails (expired refresh token, timing issue, or the refresh request being rejected), the connection breaks. This would explain why the connector works initially and then stops.
- Session/token mismatch — MCP uses
Mcp-Session-Idheaders for session continuity. If the OAuth token gets rotated mid-session but the session state on Ahrefs' side is still tied to the old token, subsequent requests fail with 401s. - Claude's connector proxy layer — Claude.ai doesn't talk to Ahrefs directly. There's an intermediary connector/proxy layer that handles OAuth, stores tokens, and forwards MCP requests. If that layer has bugs in token storage or refresh logic, the failures would be intermittent and hard to reproduce — which matches what users experience.
Without access to both systems' logs, the exact cause is hard to pin down. What's clear is that it's an integration issue between the two platforms, not a problem with either the Ahrefs MCP server or the Ahrefs API itself.
Ahrefs documents a Bearer token workaround (Method 2 in their Claude setup guide) using mcp-remote in the Claude Desktop config. That works for Claude Desktop but not for Claude.ai on the web, which is where most people hit this problem.
This is the same class of issue Suganthan Mohanadasan documented with Manus — the MCP client's auth layer failing to properly pass credentials to the Ahrefs server.
This Cloudflare Worker bypasses OAuth entirely. Claude.ai connects to your Worker as an unauthenticated MCP server — no OAuth handshake happens. The Worker then adds your Ahrefs MCP key as a Bearer token and forwards everything to Ahrefs. Claude never talks to Ahrefs directly, so the flaky OAuth flow is removed from the equation.
Claude.ai ──(no auth)──▶ Cloudflare Worker ──(Bearer token)──▶ Ahrefs MCP Server
Same data, same 95+ tools, reliable auth every time.
Ahrefs has two completely different key types. Using the wrong one is the most common setup mistake.
| MCP Key | API v3 Key | |
|---|---|---|
| Where to get it | app.ahrefs.com/user/api-access → "MCP Key" section | Same page → "API Key" section |
| Works with | Remote MCP server (api.ahrefs.com/mcp/mcp) |
Deprecated local npm server, direct API v3 |
| Plan required | Any paid plan (Lite+) | Enterprise only |
| Used here | Yes | No |
The deprecated local MCP server (the @ahrefs/mcp npm package on GitHub) is a separate system. It uses API v3 keys, requires Enterprise, and Ahrefs have marked it as outdated. Don't use it.
Go to app.ahrefs.com/user/api-access. Find the MCP Key section (not the API Key section). Generate one if you don't have it.
git clone https://github.com/matthewgkay/ahrefs-mcp-proxy.git
cd ahrefs-mcp-proxy
npm install
npx wrangler secret put AHREFS_MCP_KEY
# Paste your MCP key when prompted
npx wrangler deployYour proxy will be live at https://ahrefs-mcp.<your-subdomain>.workers.dev/mcp.
In Claude.ai, go to Settings → Integrations and add your Worker URL as a remote MCP server:
https://ahrefs-mcp.<your-subdomain>.workers.dev/mcp
That's it. Ask Claude for Ahrefs data and it'll route through your Worker.
The Ahrefs remote MCP server exposes 95+ tools:
| Category | ~Tools | What It Covers |
|---|---|---|
| Site Explorer | 24 | Backlinks, referring domains, organic keywords, top pages, DR history, competitors |
| Web Analytics | 34 | Visitors by country, device, browser, source, UTM, referrer, time series |
| Keywords Explorer | 6 | Search volume, difficulty, CPC, matching terms, related terms |
| Brand Radar | 9 | AI brand mentions, share of voice across LLMs, cited domains and pages |
| Site Audit | 3 | Crawl health, issues, page-level details |
| Rank Tracker | 5 | SERP snapshots, competitor rankings, position tracking |
| Batch Analysis | 1 | Compare up to 100 domains in a single call |
| SERP Overview | 1 | Live SERP data for any keyword |
Once connected, just ask Claude naturally:
- "Compare the backlink profiles of these three competitors."
- "What keywords drive the most traffic to example.com?"
- "Check Brand Radar — are we showing up in AI answers?"
- "Pull the SERP for 'best project management tools' and show DR for each result."
- "Run a batch analysis on these 20 domains."
A few things to know about the Ahrefs MCP API:
- Call the
doctool first before using any tool for the first time. Thetools/listresponse returns simplified schemas missing required fields and valid column names.docgives you the real schema. - Most tools need a
dateparameter inYYYY-MM-DDformat, even when the schema doesn't flag it as required. Use the first of the current month for recent data. - Monetary values are in cents. A
cpcof 450 means $4.50. - Use
mode: subdomainswhen analyzing a full domain. Thedomainmode excludes www and subdomains, which gives incomplete data for most sites. - The
selectparameter format varies. Most tools take a comma-separated string ("keyword,volume,traffic").batch-analysistakes an array (["domain_rating", "org_traffic"]). Thedoctool tells you which.
The Cloudflare Worker is a thin HTTP proxy (~50 lines of TypeScript):
- Receives MCP requests at
/mcp(any method) - Attaches your Ahrefs MCP key as a
Bearertoken in theAuthorizationheader - Forwards the request to
https://api.ahrefs.com/mcp/mcp, includingContent-Type,Accept, andMcp-Session-Idheaders - Streams the response back to the client
No data transformation, no caching, no state, no MCP SDK needed. It's a pass-through that removes the unreliable OAuth layer from the equation.
ahrefs-mcp-proxy/
├── src/
│ └── index.ts ← Cloudflare Worker (~50 lines)
├── wrangler.toml ← Worker configuration
├── package.json
├── package-lock.json
├── tsconfig.json
├── LICENSE
└── README.md
401 Unauthorized from Ahrefs: You're using an API v3 key instead of an MCP key, or the Wrangler secret wasn't set. Run npx wrangler secret put AHREFS_MCP_KEY again.
Claude can't connect to the Worker: Make sure the Worker deployed successfully (npx wrangler deploy) and the URL you added in Claude.ai ends in /mcp.
"column not found" errors from Ahrefs: Call the doc tool first to get valid column names before using a tool's select parameter. Tell Claude: "First call the doc tool for site-explorer-organic-keywords, then pull the data."
Missing data / incomplete results: Use mode: subdomains for domain-level analysis. The domain mode excludes subdomains.
Inspired by Suganthan Mohanadasan's post on solving a similar auth issue with the Ahrefs MCP server in Manus. His approach was a Python skill that calls the Ahrefs MCP server directly, bypassing the Manus connector layer. This takes the same idea and implements it as a Cloudflare Worker for Claude.ai and any other MCP client.
MIT