ahrefs-connect-mcp

A read-only MCP server for the Ahrefs API v3. It gives a model keyword-demand, SERP, and competitor-domain signals through a small set of tools, and attaches the unit cost of every call so spend stays visible.

• Keyword volume / difficulty / CPC, keyword ideas, volume history, SERP overviews, and competitor organic-keyword / top-page scans.
• Each paid result carries _meta.cost ({ rows, units, usd, basis }), taken from the Ahrefs response cost headers when present, else estimated.
• A defensive PII value-scrub runs by default (Ahrefs isn't a PII source, but a stray email/SSN in a title or URL gets caught), with an explicit opt-out.

Install

Install from npm (Node ≥ 18.18):

npm install -g @hackspaces/ahrefs-connect-mcp

This server is installed and run with node, not npx, the same way the MCP gateway consumes it.

Configure

Set your Ahrefs API key and run the installed entrypoint over stdio:

AHREFS_API_KEY=... \
  node "$(npm root -g)/@hackspaces/ahrefs-connect-mcp/dist/index.js"

Register it with any MCP client by pointing at the installed file:

{
  "mcpServers": {
    "ahrefs-connect": {
      "command": "node",
      "args": ["<entrypoint>"],
      "env": { "AHREFS_API_KEY": "..." }
    }
  }
}

Tools

| Tool | Purpose | | --- | --- | | ahrefs_keyword_overview | Volume, difficulty (KD), CPC for one or more keywords | | ahrefs_keyword_ideas | Discover matching / related / suggested keywords from a seed | | ahrefs_keyword_history | Monthly search-volume trend for a keyword | | ahrefs_serp_overview | Top organic results for a keyword + their domain metrics | | ahrefs_domain_organic_keywords | Keywords a competitor domain ranks for | | ahrefs_domain_top_pages | Top traffic-driving pages on a domain | | ahrefs_subscription_usage | Ahrefs' own limits and row usage (free) |

Cost & budget

This server does not enforce budgets. It surfaces the per-call cost in _meta.cost for visibility; the hard backstop is Ahrefs' own 402 out of credits, and ahrefs_subscription_usage reports the authoritative remaining quota. See CLAUDE.md for why the stateful ledger from the Python original was deliberately left out.

Environment

• AHREFS_API_KEY (required).
• AHREFS_DEFAULT_COUNTRY (default us), AHREFS_USD_PER_ROW (default 0.01, cost display only), and per-tool limit knobs, see .env.example.
• AHREFS_MCP_ALLOW_PII=true to disable the defensive scrub.

Development

npm install
npm run typecheck
npm run build
npm test
npm run dev            # run from source over stdio
npm run smoke -- "data analytics certificate"   # one live call

License

MIT