SE Ranking MCP Server

This Model Context Protocol (MCP) server connects AI assistants to SE Ranking's SEO data and project management APIs. It enables natural language queries for:

• Keyword research and competitive analysis
• Backlink analysis and monitoring
• Domain traffic and ranking insights
• Website audits and technical SEO
• AI search visibility tracking
• Project and rank tracking management

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 an MCP-compatible client, such as Claude Desktop or the Gemini CLI.

API Tokens

This MCP server supports two types of API access:

Get your tokens from: https://online.seranking.com/admin.api.dashboard.html

You can use one or both tokens depending on which tools you need. If you only use Data API tools, you can omit PROJECT_API_TOKEN, and vice versa.

Rate Limits

Rate limits are customizable. Contact api@seranking.com to request adjustments.

Installation

Choose the installation method that best fits your needs:

• Option 1: Docker (Recommended) - Best for standard usage, stability, and ease of updates. Use this if you just want to run the tool without managing dependencies.
• Option 2: Local Node.js Server (For Developers) - Best for development, debugging, or environments where Docker isn't available (like Replit). Use this if you need to modify the code or run a custom setup.

Option 1: Docker (Recommended)

1. Open your terminal (or Command Prompt/PowerShell on Windows).
2. Clone the project repository from GitHub:

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

3. Navigate into the new directory:

cd seo-data-api-mcp-server

4. Build the Docker Image:

docker build -t se-ranking/seo-data-api-mcp-server .
# Check that the image is built and named `se-ranking/seo-data-api-mcp-server`:
docker image ls

How to Update SEO-MCP (Docker)

To ensure you have the latest features, pull the latest changes and rebuild:

git pull origin main
docker build -t se-ranking/seo-data-api-mcp-server .

Option 2: Local Node.js Server (For Developers)

In order to run the local Node server, you need to have Node.js 20+ version installed on your machine.

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Start the server:

npm run start-http

Then your HTTP server should be running at: http://0.0.0.0:5000/mcp.

In case you'd like to modify the HOST and PORT, you can do so by creating a .env file in the root directory of the project with the settings you want to override, for example:

HOST=127.0.0.1
PORT=5555

Additionally, when running in external environments like Replit, you can set the DATA_API_TOKEN and PROJECT_API_TOKEN environment variables in the configuration panel.

Note: If you change the API token values when the server is running, you need to restart the server.

Verifying the HTTP Server

To send a sample test request and verify your setup:

./test-http-server-curl-request.sh '<your-api-token-here>'

For batch MCP Requests testing:

./test-batch-http-server-curl-request.sh '<your-api-token-here>'

Connect to Claude Desktop

Claude Desktop reads its configuration from claude_desktop_config.json.

• Click on the Claude menu and select Settings....
• In the Settings window, navigate to the Developer tab in the left sidebar.
• Click the Edit Config button to open the configuration file. This action creates a new configuration file if one doesn’t exist or opens your existing configuration.

The file is located at:

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

Example of Claude Desktop configuration for MCP server

JSON Configuration Template:

{
  "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-here>",
        "PROJECT_API_TOKEN": "<your-project-api-token-here>"
      }
    }
  }
}

• Replace the DATA_API_TOKEN and PROJECT_API_TOKEN placeholder values with your tokens (see API Tokens section).

• After saving claude_desktop_config.json, restart Claude Desktop. You should see the server under MCP Servers/Tools.

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

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

Connect to Gemini CLI

• Open the Gemini CLI settings file, which is typically located at: ~/.gemini/settings.json
• 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-here>",
        "PROJECT_API_TOKEN": "<your-project-api-token-here>"
      }
    }
  }
}

Replace the DATA_API_TOKEN and PROJECT_API_TOKEN placeholder values with your tokens (see API Tokens section).

• Save the configuration file.

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

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

Available Tools

Data API Tools

Project API Tools

Available Prompts

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.

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

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

Docker image problems

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

Verifying if the Docker container is running when you run your AI Assistant (Claude or Gemini). If you start a chat with an AI, and your MCP Server is set up properly via JSON config, 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:

CONTAINER ID   IMAGE                                    COMMAND                  CREATED          STATUS          PORTS     NAMES
de4e410ef0fd   se-ranking/seo-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 docker ps shows no running containers related to the MCP server, it usually points to a configuration issue:

• Incorrect/invalid JSON: Double-check the claude_desktop_config.json or settings.json for any syntax errors like missing commas or brackets. You can validate the JSON here: https://jsonlint.com/.

• Incorrect image name: Double-check the claude_desktop_config.json or settings.json for the correct image name se-ranking/seo-data-api-mcp-server

Docker image running, but MCP server is not visible in Claude Desktop / Gemini CLI

If the docker image is running, but the MCP server is not visible in Claude Desktop, you can investigate the container by:

docker inspect <container-id>

For the following example, the container ID is de4e410ef0fd:

CONTAINER ID   IMAGE                                    COMMAND                  CREATED          STATUS          PORTS     NAMES
de4e410ef0fd   se-ranking/seo-data-api-mcp-server       "docker-entrypoint.s…"   9 seconds ago    Up 8 seconds              musing_bhabha

Note: you can shorten the container ID in case no other containers share that prefix, ex. docker inspect de4. When you're running multiple AI chats and/or tools connected to the MCP Servers, there can be multiple containers running, but all with the same IMAGE name.

This will show you the big JSON output, where particularly important is the "Config" section, ex.:

{
  "Config": {
    "Hostname": "0977c3dc06fb",
    "Domainname": "",
    "User": "",
    "AttachStdin": true,
    "AttachStdout": true,
    "AttachStderr": true,
    "Tty": false,
    "OpenStdin": true,
    "StdinOnce": true,
    "Env": [
      "DATA_API_TOKEN=80cfee7d-xxxx-xxxx-xxxx-fc8500816bb3",
      "PROJECT_API_TOKEN=253a73adxxxxxxxxxxxxxx340aa0a939",
      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
      "NODE_VERSION=20.19.5",
      "YARN_VERSION=1.22.22",
      "NODE_ENV=production"
    ]
  }
}

Which shows you if you have the correct environment variables set.

Contributing

Prerequisites

• Node.js 20+
• npm

Running Tests

# Run all tests (compiles TypeScript first)
npm test

# Run only E2E tests
npm run test:e2e

# Run tests in watch mode
npm run test:watch

Environment Variables for Testing

Create a .env file in the project root with the following variables:

E2E Tests

E2E tests make real API calls to SE Ranking services. They are disabled by default to avoid unnecessary API usage during development.

• When E2E_ENABLED=false or unset, E2E tests are skipped
• Set E2E_ENABLED=true to run the full test suite with live API calls
• Ensure you have valid API tokens before enabling E2E tests

Other Development Commands

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format
npm run format:check

# Type check
npm run typecheck

Support

SE Ranking API documentation: https://seranking.com/api/integrations/mcp/.

In case you have any questions or need help, please contact us at api@seranking.com