SkillFoxx

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

  • 1 ★ on the repository
  • Last commit
  • MIT
MCP server

Extended access

Why this level

  • Triggers paid position checks that spend the Topvisor account balance
  • The Topvisor API key grants access to every project in the account
All reasons and checks
Russian stack

scom-82/topvisor-mcpAuthor:scom-82

Install

Services

In your terminal, with SkillFoxx CLI

npx skillfoxx add mcp/scom82-topvisor-mcp

Detects the agents on your machine, shows the access level and pins the version.

Other ways to install

Access and checks

How we review

Extended accessThe tool runs code or makes network calls and only reads external data.

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

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

MCP

Transport
stdio
Authentication
API key

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

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.

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.

How is the Topvisor MCP server different from working in the Topvisor dashboard?

The unofficial 17-tool server implements the API v2 workflow: create a project by URL, add a search engine and region, import keywords via CSV, estimate check cost and start an asynchronous position check in Yandex and Google.

What is the difference between region_key and region_index and is the result immediate?

region_key is the Topvisor catalog key used when adding a region, while region_index is the index of an already added region from topvisor_list_regions. The position check is asynchronous: a task starts first and the result is requested separately. A Topvisor API key goes in the config, the npx config is in the install block.

Discussion

No questions or reviews yet.

MCP servers
Russian stack

A paid connector service for Yandex Direct, VK and Avito with analytics, wasted-spend detection and an autopilot layer over the Direct API

MCP serverBroad access4
Russian stack

SERP, Wordstat, GSC, GA4, Yandex Webmaster, Metrika and A-Parser: eight read-only MCP servers with strict JSON and multi-account support for Claude Code

PluginExtended access8
Russian stack

An unofficial MCP server for Rush Analytics: SERP top, Wordstat, suggestions, rank tracking and AI-brand tracking, 14 tools

MCP serverExtended access

Yandex Webmaster API v4.1 MCP server

Яндекс Вебмастер MCP-сервер

Russian stack

A Python MCP server with full Yandex Webmaster API v4.1 coverage: 37 tools from diagnostics and sitemaps to important-URL monitoring

MCP serverExtended access

Yandex Webmaster MCP server (npm)

@theyahia/yandex-webmaster-mcp

Russian stack

A TypeScript MCP server for the Yandex Webmaster API: sites, indexing, search queries, sitemaps, diagnostics and recrawl, 13 tools

MCP serverExtended access6
Russian stack

A local Yandex Webmaster MCP server with a recommended weekly routine: queries, indexing, recrawl and diagnostics in order

MCP serverExtended access

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.

README badge

Report a problem