MCP

The SE Ranking MCP (Model Context Protocol) is a powerful tool that connects your SE Ranking data with large language models (LLMs) like the Claude Desktop app and Gemini CLI. This integration allows you to use natural language prompts to perform complex SEO analysis, query your project data and generate reports directly from your AI assistant.

This guide provides step-by-step instructions for installing and configuring the SE Ranking MCP server on your local machine.

Video Guide

See the SE Ranking MCP in action! This video introduces the official MCP server and demonstrates how you can turn your AI assistant into a powerful SEO tool to perform competitive analysis and find keyword opportunities in seconds.

Watch the SEO-MCP Overview on YouTube

What is an MCP for SEO?

A Model Context Protocol (MCP) acts as a specialized translator between a large language model and a specific data source. In this case, the SEO MCP allows your AI assistant to understand and interact with the SE Ranking API. It gives the model the “context” and “tools” it needs to query your domains traffic, analyze competitors, find keyword opportunities, and more, all from a simple conversation or prompt.

1. Prerequisites

Before you begin, please ensure you have the following software and accounts ready:

• SE Ranking Account: You will need an active SE Ranking account to generate an API token. If you don’t have one, you can sign up here.
• Docker: A platform for developing, shipping, and running applications in containers. If you don’t have it, you can download it from the official Docker website.
• Git: A free and open-source distributed version control system. You can download it from the official Git website.
• AI Assistant: You will need either the Claude Desktop App or the Gemini CLI installed and configured on your machine.

2. Installation

Follow these steps to install the SEO-MCP server on your local machine.

1. Open your terminal (or Command Prompt/PowerShell on Windows).

2. Clone the project repository from GitHub. This command downloads the necessary files to your machine.

git clone https://github.com/seranking/seo-data-api-mcp-server.git

4. Navigate into the new directory in your terminal:

cd seo-data-api-mcp-server

5. Build the Docker container. This command creates a local instance of the MCP server that your AI assistant will communicate with.

docker compose build

3. How to Update SEO-MCP

To ensure you have the latest features and improvements, you should update the tool periodically.

1. Navigate to your seo-data-api-mcp-server directory in the terminal.

2. Pull the latest changes from the GitHub repository.

git pull origin main

3. Rebuild the Docker container with the updates.

docker compose build

4. Configuration

Next, you need to configure your AI assistant to communicate with the local SEO-MCP server.

For Claude Desktop Users

1. Open the Claude configuration file. You can usually find it at this path on a Mac:

~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the following JSON configuration. Remember to replace the two placeholder values.

{

  "mcpServers": {

    "seo-data-api-mcp": {

      "command": "docker",

      "args": [

        "run",

        "-i",

        "--rm",

        "-e",

        "SERANKING_API_BASE",

        "-e",

        "SERANKING_API_TOKEN",

        "se-ranking/seo-data-api-mcp-server"

      ],

      "cwd": "/path/to/your/seo-data-api-mcp-server",

      "env": {

        "SERANKING_API_BASE": "https://api.seranking.com",

        "SERANKING_API_TOKEN": "YOUR_SE_RANKING_API_TOKEN"

      }

    }

  }

}

• "cwd": This should be the full, absolute path to the seo-data-api-mcp-server folder you cloned.
• "SERANKING_API_TOKEN": Replace this with your actual API token from the SE Ranking API Dashboard.

3. Save the configuration file and restart your Claude desktop application for the changes to take effect.

4. To verify the setup, ask Claude: do you have access to MCP? It should respond by listing seo-data-api-mcp.

5. Your setup is complete! You can now run complex SEO queries using natural language.

For Gemini CLI Users

1. Open the Gemini CLI settings file, which is typically located at: ~/.gemini/settings.json
2. Add the following JSON configuration, making sure to replace the two placeholder values.

{

  "mcpServers": {

    "seo-data-api-mcp": {

      "command": "docker",

      "args": [

        "run",

        "-i",

        "--rm",

        "-e",

        "SERANKING_API_BASE",

        "-e",

        "SERANKING_API_TOKEN",

        "se-ranking/seo-data-api-mcp-server"

      ],

      "cwd": "/path/to/your/seo-data-api-mcp-server",

      "env": {

        "SERANKING_API_BASE": "https://api.seranking.com",

        "SERANKING_API_TOKEN": "YOUR_SE_RANKING_API_TOKEN"

      }

    }

  }

}

• "cwd": This should be the full, absolute path to the seo-data-api-mcp-server folder.
• "SERANKING_API_TOKEN": Use your personal API token, which you can generate from the SE Ranking API Dashboard.

3. Save the configuration file.

4. To verify the setup, launch the Gemini CLI by running gemini in your terminal. Once the interface is active, press Ctrl+T to view the available MCP servers. Ensure seo-data-api-mcp is listed.

5. Your setup is complete! You can now run complex SEO queries using natural language.

5. Usage Example: Finding Keyword Opportunities

With the configuration complete, you can now use natural language prompts to interact with your SE Ranking data. Here is an example prompt to identify low-hanging keyword opportunities for a domain.

Example Prompt

Copy and paste the following into your configured AI assistant:

Use the seo-mcp to identify the Keywords my domain is overlooking and find low-hanging fruit opportunities.

1. Analyze my domain's keyword performance:

   - Find keywords my domain has lost (not ranking) using the tool for domainKeywords with pos_change=lost.

   - Find keywords where my domain's position has gone down using the tool for domainKeywords with pos_change=down.
2. Conduct a competitive analysis:

   - Identify my top 2 competitors by finding all competitors with the tool for domainCompetitors and ordering them by common_keywords DESC.

   - Find 30 keywords that these competitors are ranking for but my domain is not. Use the domainKeywordsComparison tool with diff=1, order_field=volume, and order_type=DESC.
3. Identify new keyword opportunities:

   - For 10 of the competitor keywords found in the previous step, use the tools for relatedKeywords and similarKeywords to find the top 5 related and similar keywords for each, ordered by volume DESC.
4. Synthesize and Report:

   - Create a final report of the findings. In the report, highlight potential low-hanging fruit from the new keyword opportunities by analyzing their CPC and keyword difficulty.
Domain to review: seranking.com

Market: us

What This Prompt Does

This prompt instructs the model to perform a comprehensive competitive analysis by:

• Finding Lost & Declining Keywords: It first identifies keywords for seranking.com that have either been lost from the rankings or have dropped in position.
• Identifying Top Competitors: It finds all organic competitors and sorts them to identify the top two based on the number of shared keywords.
• Uncovering Competitor-Ranked Keywords: It compares seranking.com against its top competitors to find 30 high-volume keywords that they rank for, but seranking.com does not.
• Generating a Final Report: Finally, it synthesizes all of this information into a concise report, highlighting the most promising opportunities for growth.

Troubleshooting

If you’re having trouble getting the MCP server to connect, here are a few steps to diagnose the issue.

Verifying the Container is Running

When you run your AI Assistant (Claude or Gemini), it should automatically start the Docker container. To check if it’s running, open your terminal and run:

docker ps

If it’s working correctly, you will see an output similar to this, showing the seranking/data-api-mcp-server image is Up:

CONTAINER ID   IMAGE                               COMMAND                  CREATED          STATUS          PORTS     NAMES

de4e410ef0fd   seranking/data-api-mcp-server       "docker-entrypoint.s…"   9 seconds ago    Up 8 seconds              musing_bhabha

This confirms that your AI assistant has successfully started the container and it’s listening for connections.

If No Container is Running

If docker ps shows no running containers related to the MCP server, it usually points to a configuration issue:

• Incorrect JSON: Double-check the claude_desktop_config.json or settings.json for any syntax errors like missing commas or brackets.
• Incorrect Path: Ensure the "cwd" path in your JSON configuration is the correct, full absolute path to the seo-data-api-mcp-server directory.

Inspecting the Container for Details

For a more in-depth look at the container’s configuration, you can use the docker inspect command.

1. First, get the CONTAINER ID from the docker ps command (e.g., de4e410ef0fd). You only need the first few unique characters.
2. Run the inspect command:docker inspect de4e
3. This command will output a large JSON object containing all the configuration details for that container, including environment variables like your SERANKING_API_BASE and SERANKING_API_TOKEN. You can review this information to ensure your API key and other settings were passed to the container correctly.