MCP

The SE Ranking MCP (Model Context Protocol) server connects SE Ranking data with large language models (LLMs) such as Claude Desktop, Gemini CLI, and ChatGPT. It enables natural-language SEO analysis, competitive research, reporting, and project management directly from your AI assistant.

This guide explains how to install and configure the MCP server locally or remotely and connect it to supported AI assistants:

• Installation
• Connecting to Claude Desktop
• Connecting to Gemini CLI
• Remote server setup (ChatGPT/Agent Builder)
• Usage example
• Troubleshooting

Prerequisites

• SE Ranking account: You need an active SE Ranking account to generate API tokens. If you don’t have one, sign up here.
• Docker: This is an installation method we recommend. If you don’t have the tool, download it from the official Docker website.
• Git: Required to clone the repository (you can download it from the official Git website).
• AI Assistant: Claude Desktop, Gemini CLI, or ChatGPT Plus (via Agent Builder).
• Node.js 20+: Required only for local Node.js/developer installation.

API tokens

The MCP server supports two independent SE Ranking API tokens, each mapped to a specific tool set. You can find instructions on how to generate your API tokens here.

Rate limits

Rate limits can be increased on request. Contact [email protected].

Installation

Option 1. Docker (recommended)

Best for standard usage, stability, and easy updates without managing dependencies.

1. Open your terminal (or Command Prompt/PowerShell on Windows) and clone the repository:

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

cd seo-data-api-mcp-server

2. Build the Docker image:

docker build -t se-ranking/seo-data-api-mcp-server .

3. Verify the image:

docker image ls

Updating the Docker image:

git pull origin main

docker build -t se-ranking/seo-data-api-mcp-server .

Option 2. Local Node.js server (developers/Replit)

Recommended for development, debugging, or platforms where Docker is unavailable.

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Start the HTTP MCP server:

npm run start-http

The server will be available at:

http://0.0.0.0:5000/mcp

Configuration via .env:

You can override defaults by creating a .env file. For example:

HOST=127.0.0.1

PORT=5555

DATA_API_TOKEN=your-data-api-token

PROJECT_API_TOKEN=your-project-api-token

Connecting to Claude Desktop

Step 1. Open the Claude Desktop configuration file

Claude Desktop reads the MCP configuration from claude_desktop_config.json located at:

• macOS: /Users/your-username/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %AppData%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

If claude_desktop_config.json already exists, open it with any text editor. If claude_desktop_config.json does not exist, duplicate any existing file in the Claude folder, rename the copy to claude_desktop_config.json, and open it with a text editor.

To locate the file via Finder:

• Open Finder.
• Go to your user folder.
• Press Command + Shift + . to show hidden folders.
• Open Library → Application Support → Claude.

Example configuration:

{

  "mcpServers": {

    "seo-data-api-mcp": {

      "command": "docker",

      "args": [

        "run",

        "-i",

        "--rm",

        "-e",

        "DATA_API_TOKEN",

        "-e",

        "PROJECT_API_TOKEN",

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

      ],

      "env": {

        "DATA_API_TOKEN": "your-data-api-token",

        "PROJECT_API_TOKEN": "your-project-api-token"

      }

    }

  }

}

Step 2. Save the file and restart Claude Desktop

Step 3. Verify connection

Verify the connection by asking Claude:

Do you have access to MCP?

It should respond by confirming access:

Connecting to Gemini CLI

Step 1. Open the Gemini CLI configuration file

/Users/your-username/.gemini/settings.json

Step 2. Add JSON configuration

Add the following JSON configuration, making sure to replace the API token placeholder values:

{

  "mcpServers": {

    "seo-data-api-mcp": {

      "command": "docker",

      "args": [

        "run",

        "-i",

        "--rm",

        "-e",

        "DATA_API_TOKEN",

        "-e",

        "PROJECT_API_TOKEN",

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

      ],

      "env": {

        "DATA_API_TOKEN": "your-data-api-token",

        "PROJECT_API_TOKEN": "your-project-api-token"

      }

    }

  }

}

Step 3. Save the configuration file

Step 4. Verify connection

Verify the connection by running gemini in your terminal. Then press Ctrl+T and confirm seo-data-api-mcp is listed.

Remote server setup (ChatGPT/Agent Builder)

You can run the MCP server remotely (for example, on Replit) and connect it to OpenAI Agent Builder using the HTTP MCP interface.

Step 1. Deploy the server

1. Import the GitHub repository into Replit.

2. Set DATA_API_TOKEN and PROJECT_API_TOKEN as environment variables.

3. Run:

npm install

npm run build

npm run start-http

4. Ensure the public URL ends with /mcp. For example: https://xxxxxx.replit.dev/mcp.

Step 2. Connect in Agent Builder

1. Open OpenAI Agent Builder.

2. Create a new workflow:

3. Select the agent node → Tools → Add tool.

4. Choose Hosted → MCP server.

5. Add a new server:

• URL: your /mcp endpoint
• Label: e.g. SE_Ranking_MCP
• Authentication: API key
• Token: your SE Ranking API token

After connecting, Agent Builder will automatically list all available MCP tools.

Available tools and prompts

Data API tools (prefix DATA_):

• AI search (AI Overview, prompts, brand discovery)
• Backlinks
• Domain analysis
• Keyword research
• Website audits

Project API tools (prefix PROJECT_):

• Account & subscription
• Rank tracking & competitors
• Backlink monitoring
• Keyword groups
• Marketing plan
• Project & sub-account management

Available prompts

Usage example: Finding keyword opportunities

This prompt instructs the AI assistant to perform a full competitive keyword analysis by identifying lost and declining keywords for your domain, determining top organic competitors based on shared keywords, uncovering high-volume keywords competitors rank for but you do not, and synthesizing the results into a prioritized opportunity report.

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 getDomainKeywords with pos_change=lost.

 - Find keywords where my domain's position has gone down using the tool for getDomainKeywords with pos_change=down.

2. Conduct a competitive analysis:

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

 - Find 30 keywords that these competitors are ranking for but my domain is not. Use the getDomainKeywordsComparison 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 getRelatedKeywords and getSimilarKeywords 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

Troubleshooting

Below are some issues you may encounter when getting the MCP server to connect:

• Invalid JSON in Claude/Gemini config
• Incorrect Docker image name
• Missing API tokens

If you need further assistance, contact us at [email protected].

How to troubleshoot:

Verify the Docker container. You should see se-ranking/seo-data-api-mcp-server running.

docker ps

Inspect environment variables:

docker inspect 

Confirm DATA_API_TOKEN and/or PROJECT_API_TOKEN are present.

Video: SE Ranking MCP in Action

See how the MCP server enables competitor analysis and fast keyword research using AI assistants.