Overview

This repository provides a free MCP (Model Context Protocol) server that exposes SEO-focused tools to LLMs and developer workflows. It wraps Ahrefs functionality (backlinks and keyword ideas) behind simple HTTP endpoints that conform to a tool-style interface so models and automation systems can query backlink data and generate keyword suggestions programmatically.

The server is useful for developers building AI assistants, SEO automations, or data pipelines that need contextual SEO signals. Instead of embedding raw Ahrefs API calls inside every integration, you can run this MCP server once, centralize configuration (API tokens, rate limits), and give models or services a consistent, documented toolset to request backlinks or keyword ideas.

Features

Exposes Ahrefs backlinks retrieval as a tool endpoint
Generates keyword ideas based on seed keywords or domains
Simple REST API compatible with MCP-style tool manifests
Environment-driven configuration for API keys and rate limits
Docker support for quick deployment
Example request/response patterns for easy integration with LLMs or automation scripts

Installation / Configuration

Clone the repository, configure environment variables, and run the server. The examples below use a Node.js-based workflow; the repo also includes a Dockerfile.

Clone the repo

git clone https://github.com/cnych/seo-mcp.git
cd seo-mcp

Install dependencies (Node.js)

# using npm
npm install

# or using yarn
yarn install

Set environment variables

Create a .env file or export variables in your environment. Minimal required values:

AHREFS_API_TOKEN=your_ahrefs_api_token_here
MCP_PORT=8080
RATE_LIMIT_PER_MINUTE=60

Optional configuration:

AHREFS_API_URL=https://apiv2.ahrefs.com
LOG_LEVEL=info

Run the server

npm start
# or for development
npm run dev

Run with Docker

docker build -t seo-mcp .
docker run -e AHREFS_API_TOKEN=your_token -p 8080:8080 seo-mcp

Available Tools / Resources

The server exposes a small set of tools designed to be used as MCP-style resources for LLMs or other orchestration systems.

Tool name	Endpoint	Method	Input (JSON)	Output (JSON)
ahrefs-backlinks	/tool/ahrefs-backlinks	POST	{ “target”: “https://example.com”, “limit”: 100 }	{ “backlinks”: [ { “source”: “…”, “anchor”: “…”, “refDomain”: “…”, “date”: “…” } ] }
keyword-ideas	/tool/keyword-ideas	POST	{ “seed”: “marketing automation”, “max_results”: 20 }	{ “keywords”: [ { “keyword”: “…”, “volume”: 1234, “difficulty”: 0.45 } ] }
manifest	/mcp/tools	GET	—	{ “tools”: [ { “name”: “…”, “description”: “…”, “schema”: {…} } ] }

Example: request the tools manifest

curl http://localhost:8080/mcp/tools

Example: fetch backlinks for a domain

curl -X POST http://localhost:8080/tool/ahrefs-backlinks \
  -H "Content-Type: application/json" \
  -d '{"target":"https://example.com","limit":50}'

Example: request keyword ideas

curl -X POST http://localhost:8080/tool/keyword-ideas \
  -H "Content-Type: application/json" \
  -d '{"seed":"product analytics","max_results":15}'

Use Cases

LLM-assisted SEO audits: Connect the MCP server to an LLM tool runner so the model can request backlinks for a target domain during an audit conversation, then synthesize insights like toxic links, top referrers, and anchor text distribution.
Keyword research automation: Use the keyword-ideas endpoint in a content planning pipeline to automatically expand a seed list into prioritized keyword suggestions (volume and difficulty), then feed results into editorial briefs.
Competitive backlink monitoring: Schedule regular runs that call ahrefs-backlinks for competitor domains, store results in a database, and notify teams when new high-value referring domains appear.
Prompt enrichment for agents: When using an LLM agent that supports tools, expose this server as a tool manifest so agents can call precise SEO functions instead of relying on hallucinated data.

Concrete example workflow:

Agent receives prompt: “Build a content plan for migrating marketing blog articles.”
Agent calls keyword-ideas with seed “content migration” and gets 20 keywords ranked by volume and difficulty.
Agent calls ahrefs-backlinks for the top competitor URLs returned from keyword research to identify content patterns and linkable assets.
Agent compiles a prioritized content calendar and backlink outreach suggestions.

API Response Reference

Backlinks response (excerpt):

{
  "backlinks": [
    {
      "source": "https://referrer.example/page",
      "anchor": "useful guide to migration",
      "refDomain": "referrer.example",
      "date": "2026-03-01",
      "type": "dofollow",
      "ahrefs_metrics": {
        "domain_rating": 45,
        "traffic": 1200
      }
    }
  ],
  "total": 123
}

Keyword ideas response (excerpt):

{
  "keywords": [
    {
      "keyword": "content migration checklist",
      "volume": 1900,
      "difficulty": 0.32,
      "intent": "informational"
    }
  ]
}

Further notes

The server is a thin wrapper around Ahrefs endpoints; your Ahrefs API quota and permissions determine what data is available.
Rate limiting and caching can be configured via environment variables to manage API usage.
Review the repository’s README and code for advanced configuration (authentication, custom schemas, and integration examples).

Free MCP Server: Ahrefs Backlinks and Keyword Ideas