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, Gemini CLI, and Chatgpt. This integration allows you to use natural language prompts to perform complex SEO analysis, query SEO 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 for Claude and Gemini, and for connecting to the remote server for ChatGPT.

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

Quick Links

• Local Server Setup (for Claude & Gemini)
• Remote Server Setup (for ChatGPT)
• Prompt Example: Finding Keyword Opportunities
• Troubleshooting

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.

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 the Claude Desktop App, the Gemini CLI or a ChatGPT Plus account.

For Local Server

1. Installation (For Claude & Gemini)

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

2. 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

3. 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_TOKEN",

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

      ],

      "env": {

        "SERANKING_API_TOKEN": "#your-api-token-here#"

      }

    }

  }

}

• "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_TOKEN",

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

      ],

      "env": {

        "SERANKING_API_TOKEN": "#your-api-token-here#"

      }

    }

  }

}

• "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.

For Remote Server (ChatGPT Users)

You can connect ChatGPT to your SE Ranking data using a Remote MCP server, which does not require a local Docker installation. This involves running the SE Ranking MCP server on a cloud platform like Replit and then connecting it to OpenAI. This method is ideal for using the MCP with OpenAI Agent Builder.

Part 1: Deploy the MCP Server on Replit

First, you’ll set up a personal instance of the SE Ranking MCP server. An easy way to run the remote server is using Replit.

1. Create a new Replit project

a. Navigate to replit.com and click + Create Repl.

b. In the pop-up window, select Import from GitHub.

c. Paste the following repository URL into the field:

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

d. Click Import from GitHub. Replit will now clone the repository and prepare the environment.

2. Automated Deployment

You don’t need to run any commands manually. Replit’s AI agent will automatically handle the entire setup process:

• Installs Dependencies: Runs npm install in the background.
• Builds and Starts: Runs npm run build and npm run start:http to compile the project and launch the server.

You can watch the progress in the Workflows pane.

3. Get Your Public URL

Once the automated setup is complete, your server will be live. The WebView tab will open, and the deployment URL will be shown.

On free Replit accounts, server URLs are active for as long as the editor is active, so while you are testing, you’ll need to keep the browser tab open. You can get a URL for your MCP server by clicking on the chainlink icon:

In the long dev URL, ensure it ends with /mcp, which is the server-sent events (streaming) interface to the MCP server. This is the URL you will use to import your connector in the prompts dashboard and the agent builder. An example Replit URL looks like:

https://777xxx.janeway.replit.dev/mcp

2. Connect Your Server in Agent Builder

With your remote MCP server running, you can now connect it to a new agent workflow. OpenAI’s Agent Builder provides a visual canvas to build, configure, and test your agent.

Step 1: Create a New Workflow

1. Navigate to the OpenAI Agent Builder.
2. You’ll see a dashboard with templates for common use cases. For this guide, click the + Create button to start a blank workflow.

Step 2: Add Your MCP Server as a Tool

1. By default, your workflow will have a Start node connected to an Agent node. Click on the “My agent” node to open its configuration panel on the right.

2. In the agent configuration panel, locate the Tools section and click the + icon.

3. From the dropdown menu, select Hosted, and then choose MCP server.

4. A dialog will appear showing available connectors. Click the + Server button in the top right to add your custom server.

Step 3: Configure the Server Connection

1. In the “Connect to MCP Server” window, fill in the following details:
   • URL: Paste the public URL of your running Replit MCP server.
   • Label: Give your server a recognizable name (e.g., SE_Ranking_MCP).
   • Description (Optional): Briefly describe what the server does.
   • Authentication: Select Access token / API key and paste in your SE Ranking API Token.
2. Click Connect.

Step 4: Verify the Connection

1. After a successful connection, the dialog will close, and you will see your newly added MCP server listed under the Tools section for your agent.

2. Agent Builder will automatically inspect the server and display a list of all the available tools (e.g., backlinksAll, domainOverview, etc.) that your agent can now use.

You are all set! Your agent is now equipped with the full suite of SE Ranking data tools and is ready for you to add instructions, configure its behavior, and test its capabilities in the preview panel.

Usage Example: Finding Keyword Opportunities

With the configuration complete, you can now use natural language prompts to interact with your SE Ranking data.

Find all prompts here: https://help.seranking.com/hc/en-us/articles/22903914755100-Prebuilt-SEO-Prompts-for-SE-Ranking-MCP-Server

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.

🔎 Want more templates? Explore dozens of ready‑made prompts (Keyword Research, Domain Analysis, AI Search, Backlink Analysis, and more):
https://help.seranking.com/hc/en-us/articles/22903914755100-Prebuilt-SEO-Prompts-for-SE-Ranking-MCP-Server

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_TOKEN. You can review this information to ensure your API key and other settings were passed to the container correctly.