Topvisor MCP server

@scom82/topvisor-mcp

An unofficial MCP server for the Topvisor API v2: 17 tools for tracking Yandex and Google rankings by project and region

MCP serverRussian stack

scom-82/topvisor-mcpAuthor:scom-82

Install

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/scom82-topvisor-mcp

Detects the agents on your machine, checks the risk and pins the version.

Other ways to install

Run in a terminal

claude mcp add --transport stdio --env 'TOPVISOR_USER_ID=<TOPVISOR_USER_ID value>' --env 'TOPVISOR_API_KEY=<your TOPVISOR_API_KEY>' topvisor -- npx -y @scom82/topvisor-mcp

Or add to the file .mcp.json, in the project

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Install in Cursor

The button opens the agent and offers to add the server. If nothing happens, copy the config below.

Add to the file ~/.cursor/mcp.json, for all projects

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. For a single project, put the same block into .cursor/mcp.json.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Install in VS Code

The button opens the agent and offers to add the server. If nothing happens, copy the config below.

Run in a terminal

code --add-mcp '{"name":"topvisor","type":"stdio","command":"npx","args":["-y","@scom82/topvisor-mcp"],"env":{"TOPVISOR_USER_ID":"<TOPVISOR_USER_ID value>","TOPVISOR_API_KEY":"<your TOPVISOR_API_KEY>"}}'

Or add to the file .vscode/mcp.json, in the project

{
  "servers": {
    "topvisor": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the servers key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Run in a terminal

codex mcp add topvisor --env 'TOPVISOR_USER_ID=<TOPVISOR_USER_ID value>' --env 'TOPVISOR_API_KEY=<your TOPVISOR_API_KEY>' -- npx -y @scom82/topvisor-mcp

Or add to the file ~/.codex/config.toml, for all projects

[mcp_servers.topvisor]
command = "npx"
args = ["-y", "@scom82/topvisor-mcp"]
env = { TOPVISOR_USER_ID = "<TOPVISOR_USER_ID value>", TOPVISOR_API_KEY = "<your TOPVISOR_API_KEY>" }

If the file already exists, append the block to the end.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.gemini/settings.json, for all projects

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.config/devin/mcp_config.json, for all projects

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. Legacy Cascade keeps the MCP config in ~/.codeium/windsurf/mcp_config.json.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Formerly Windsurf.

Add to the file cline_mcp_settings.json, for all projects

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key. Open the settings file in Cline: MCP Servers tab, Configure MCP Servers.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file .roo/mcp.json, in the project

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

A fork of Roo Code, same .roo folders.

Add to the file opencode.json, in the project

{
  "mcp": {
    "topvisor": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "environment": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcp key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file ~/.config/zed/settings.json, for all projects

{
  "context_servers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the context_servers key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

Add to the file .codeassistant/mcp.json, in the project

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": [
        "-y",
        "@scom82/topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "<TOPVISOR_USER_ID value>",
        "TOPVISOR_API_KEY": "<your TOPVISOR_API_KEY>"
      }
    }
  }
}

If the file already exists, add the server inside the mcpServers key.

Keys and settings

TOPVISOR_USER_IDrequired
TOPVISOR_API_KEYsecret, required

Replace the values in angle brackets with your own. Keys never go into install links and are not stored by us.

You will need: Node.js

Checked against the repository on Sep 25, 2026, commit f22f06c.

Text for your agent

Add the server to your client config with the command npx -y @scom82/topvisor-mcp and the TOPVISOR_USER_ID and TOPVISOR_API_KEY variables from your Topvisor account settings.

Other ways from the author

{
  "mcpServers": {
    "topvisor": {
      "command": "npx",
      "args": ["-y", "@scom82/topvisor-mcp"],
      "env": {
        "TOPVISOR_USER_ID": "your_user_id",
        "TOPVISOR_API_KEY": "your_api_key"
      }
    }
  }
}

Snippet from the README, npx fetches the package on its own, no local install needed.

This is third-party code. Review the repository files before installing.

What it does

The server implements the full Topvisor workflow: create a project by URL, add a search engine and region, import keywords via CSV, preview a check's cost, submit an asynchronous position check, read history, a two-date summary, a position-distribution chart and SERP snapshots, plus check the account balance. It separately documents the confusion between region_key (the catalog id used when adding a region) and region_index (the sequential number Topvisor assigns afterward and which every other call expects). The README gives a table of real values for several cities to show these numbers are not guaranteed to match.

Who it is for. For SEO specialists with a Topvisor account who want to track Yandex and Google rankings through an agent.

Good fit when

You already have a paid Topvisor account with a check balance
You need both Yandex and Google in one region-based rank tracking setup
You need SERP snapshots at the time of a position check

Not a fit when

You have no Topvisor account: the server only wraps its API, it does not work without one
You need an immediate result rather than an asynchronous queue with manual polling

Example request

Check green-line24.ru's rankings for buy windows in Samara and Tolyatti

Limitations

Position checks are asynchronous and can take minutes to hours, there is no built-in wait, you must manually poll topvisor_list_projects. Some edit and delete methods are undocumented by Topvisor and are only reachable through the generic topvisor_request. The API's rate limits are undocumented and the server does not retry on them. Unofficial tool, explicitly not affiliated with Topvisor.

How to disable. Remove the topvisor block from your MCP client config.

MCP

Transport: stdio
Authentication: API key

Environment variables
Environment variables
TOPVISOR_USER_ID required	User ID from Topvisor account settings
TOPVISOR_API_KEY required, secret	API key, generated in Topvisor account settings
TOPVISOR_API_URL	Defaults to https://api.topvisor.com/v2/json
TOPVISOR_HTTP_TIMEOUT_MS	Request timeout, defaults to 30000 ms

Security check

Triggers paid position checks that spend the Topvisor account balance
The Topvisor API key grants access to every project in the account

README in short

The English README lists the 17 tools in a table, npx-based installation with no local build, a step-by-step example of Topvisor's stateful model from project creation to reading history, dedicated sections on the region_key vs region_index confusion, the async position check, the SERP snapshot format, and known API quirks like HTTP 200 on errors.

FAQ

What is the difference between region_key and region_index?

region_key is the catalog id used when adding a region via topvisor_add_region, while region_index is the sequential number Topvisor assigns afterward and which every other call needs. These numbers are not guaranteed to match, call topvisor_list_regions to get it.

Does a position check return results immediately?

No, topvisor_check_positions only queues a job on Topvisor's side and returns projectsIds, results must be fetched separately by polling topvisor_list_projects and then calling topvisor_get_history.

DataLens Skills

Official

Official DataLens (Yandex) skills for Claude Code, Codex and OpenCode: SDK, HTML reports and RLS resolution

SkillMedium riskRussian stackNo VPN needed12

Yandex Metrika MCP Server

Editors’ pick

A Yandex Metrika MCP server generated from the API spec: 108 methods, 10 tools declared by default, transparent filters and response metadata

MCP serverMedium riskRussian stackNo VPN needed2

OpenSEO

Official

An open MCP server and agent skill set for SEO: keyword research, competitors, backlinks and site audits powered by DataForSEO

MCP serverMedium risk21.5K

Claude SEO

A Claude Code plugin for SEO audits: technical SEO, E-E-A-T, schema, local and AI search via parallel subagents

PluginHigh risk17.9K

Install

What it does

Good fit when

Not a fit when

Example request

Limitations

MCP

Security check

README in short

FAQ

Related

DataLens Skills

Yandex Metrika MCP Server

OpenSEO

Claude SEO