Backlinks (Ahrefs) MCP server

This SEO MCP server provides an API to retrieve SEO data from Ahrefs, handling CAPTCHA solving, authentication, and data retrieval with built-in caching for better performance.

Installation

Prerequisites

• Python 3.10 or higher
• CapSolver account and API key (register here)

Install from PyPI

pip install seo-mcp

Or use uv:

uv pip install seo-mcp

Manual Installation

1. Clone the repository:

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

2. Install dependencies:

   pip install -e .
   # Or
   uv pip install -e .
   

3. Set the CapSolver API key:

   export CAPSOLVER_API_KEY="your-capsolver-api-key"
   

Usage

Run the Service

You can run the service in Cursor IDE:

In the Cursor settings, switch to the MCP tab, click the +Add new global MCP server button, and input:

{
  "mcpServers": {
    "SEO MCP": {
      "command": "uvx",
      "args": ["--python", "3.10", "seo-mcp"],
      "env": {
        "CAPSOLVER_API_KEY": "CAP-xxxxxx"
      }
    }
  }
}

You can also create a .cursor/mcp.json file in the project root directory with the same content.

API Reference

The service provides the following MCP tools:

Get Backlinks List

get_backlinks_list(domain: str)

Get the backlinks of a domain.

Parameters:

• domain (string): The domain to analyze (e.g. "example.com")

Returns: A JSON object containing an overview of domain statistics and a list of backlinks.

Keyword Generator

keyword_generator(keyword: str, country: str = "us", search_engine: str = "Google")

Generate keyword ideas.

Parameters:

• keyword (string): The seed keyword
• country (string): Country code (default: "us")
• search_engine (string): Search engine (default: "Google")

Returns: A JSON array of keyword suggestions with volume, difficulty, and CPC data.

Get Traffic

get_traffic(domain_or_url: str, country: str = "None", mode: str = "subdomains")

Get traffic estimation for a domain.

Parameters:

• domain_or_url (string): The domain or URL to analyze
• country (string): Country filter (default: "None")
• mode (string): Analysis mode ("subdomains" or "exact")

Returns: A JSON object containing traffic history, averages, top pages, countries, and keywords.

Keyword Difficulty

keyword_difficulty(keyword: str, country: str = "us")

Get the keyword difficulty score.

Parameters:

• keyword (string): The keyword to analyze
• country (string): Country code (default: "us")

Returns: A JSON object with difficulty score, SERP data, and related keywords.

Troubleshooting

• CapSolver API key error: Check the CAPSOLVER_API_KEY environment variable
• Rate limiting: Reduce request frequency
• No results: The domain may not be indexed by Ahrefs
• Other issues: See the GitHub repository

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.