SEO Research

The SEO Research MCP server allows you to integrate Ahrefs’ SEO data directly into AI-powered development environments.

It utilizes the Model Context Protocol (MCP) to connect your IDE (Cursor, Claude Desktop, or Windsurf) with external SEO metrics.

Features

• 🔗 Backlink Analysis: Retrieves domain ratings, total backlink counts, and reference domain statistics. It identifies whether links come from educational (.edu) or government (.gov) sources.
• 🔑 Keyword Research: Generates related keyword ideas based on a seed term. You can specify the target country and search engine preference.
• 📊 Traffic Analysis: Estimates monthly traffic and traffic costs. It breaks down data by top pages, countries, and performing keywords.
• 📈 Keyword Difficulty: Calculates a difficulty score (KD) and provides a full breakdown of the Search Engine Results Page (SERP) for analysis.

Use Cases

• Competitor Analysis During Development: You can check a competitor’s domain rating and top pages while building a landing page.
• Content Optimization in Markdown: Technical writers working in an IDE can query keyword difficulty scores immediately.
• Programmatic SEO Validation: Developers building static site generators or directory sites can test the viability of specific niches.

How to Use Ii

Installation

Option 1: Install via PyPI (Recommended)

pip install seo-mcp

Users utilizing uv should run:

uv pip install seo-mcp

Option 2: Install from Source

git clone https://github.com/egebese/seo-research-mcp.git
cd seo-research-mcp
pip install -e .

IDE Configuration Guides

You must configure your specific IDE to recognize the MCP server. Locate your editor below and follow the exact JSON structure.

Claude Desktop

1. Navigate to Settings → Developer → Edit Config.
2. This opens your claude_desktop_config.json file.
3. Insert the following configuration object. Replace YOUR_API_KEY_HERE with your actual CapSolver key.

{
  "mcpServers": {
    "seo-research": {
      "command": "uvx",
      "args": ["--python", "3.10", "seo-mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

4. Restart Claude Desktop. A hammer icon will appear in the input area if the connection is successful.

Cursor

Cursor requires a specific file path for global availability.

1. Create or edit the file located at ~/.cursor/mcp.json.
2. Paste the configuration below:

{
  "mcpServers": {
    "seo-research": {
      "command": "uvx",
      "args": ["--python", "3.10", "seo-mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

3. Verify the installation by going to File → Preferences → Cursor Settings → MCP. You should see seo-research listed under Available Tools.

Windsurf

1. Open the settings via Cmd + Shift + P (Mac) or Ctrl + Shift + P (Windows) and search for “Open Windsurf Settings”.
2. Navigate through the menu: Cascade → MCP Servers → Edit raw mcp_config.json.
3. Add the server configuration:

{
  "mcpServers": {
    "seo-research": {
      "command": "uvx",
      "args": ["--python", "3.10", "seo-mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

VS Code (GitHub Copilot)

This requires VS Code version 1.102+ and the GitHub Copilot extension.

1. Create a file named .vscode/mcp.json in the root of your current workspace.
2. Add the following content:

{
  "servers": {
    "seo-research": {
      "command": "uvx",
      "args": ["--python", "3.10", "seo-mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

3. Click theStart button that appears within the JSON file editor.
4. Toggle MCP tools in the Chat view and use #seo-research to reference it.

Zed

1. Open your settings.json file.
2. Add the context_servers block:

{
  "context_servers": {
    "seo-research": {
      "command": {
        "path": "uvx",
        "args": ["--python", "3.10", "seo-mcp"],
        "env": {
          "CAPSOLVER_API_KEY": "YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

3. Open the Agent Panel and look for a green indicator dot next to seo-research.

Available Tools

get_backlinks_list(domain)

• Input: domain (string, e.g., “example.com”)
• Returns: An object containing overview (Domain Rating, total backlinks) and a backlinks array detailing specific anchors, source URLs, and target URLs.

keyword_generator(keyword, country?, search_engine?)

• Input:
  • keyword (string): The seed term.
  • country (string, optional): Target country code (default: “us”).
  • search_engine (string, optional): Platform to analyze (default: “Google”).
• Returns: A list of objects containing the keyword, search volume, and difficulty score.

get_traffic(domain_or_url, country?, mode?)

• Input:
  • domain_or_url (string): The target website.
  • country (string, optional): Specific region or “None” for global.
  • mode (string, optional): Scope of analysis (“subdomains” or “exact”).
• Returns: Traffic averages, cost estimates, top pages, and top keywords.

keyword_difficulty(keyword, country?)

• Input:
  • keyword (string): The term to analyze.
  • country (string, optional): Target country code (default: “us”).
• Returns: A difficulty score (integer) and a list of current SERP results.

FAQs

Q: Is this tool officially affiliated with Ahrefs?
A: No. This is an independent project that retrieves data from Ahrefs. It is for educational and research purposes only.

Q: Does this cost money to use?
A: The software itself is open-source and free. However, you must pay for CapSolver credits to handle the CAPTCHA verification required to fetch the data.

Q: Can I use this with ChatGPT or the OpenAI web interface?
A: No. This is an MCP server designed for local IDEs and desktop applications that support the Model Context Protocol, such as Claude Desktop and Cursor.