@scom82/topvisor-mcp

Unofficial. This is an unofficial MCP server and is not affiliated with or endorsed by Topvisor.

An MCP (Model Context Protocol) server for the Topvisor API v2. Provides 17 tools for Yandex/Google rank tracking: projects, keywords, searchers and regions, position check submission, history, summary charts, SERP snapshots, and account balance. Implements the stateful Topvisor project model — set up project → add searchers/regions → import keywords → submit check (async) → read history.

Installation

Via npx (recommended — through MCP config)

No local install needed. Configure your MCP client and npx handles the rest:

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

From source

git clone https://github.com/SCom-82/topvisor-mcp.git
cd topvisor-mcp
npm install
npm run build
node dist/index.js

Related MCP server: YouTube MCP Server

Configuration

The server starts without credentials — tools/list and topvisor_services work without them. Credentials are validated lazily on the first real API call.

Claude Desktop / Claude Code config

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

Tools

Stateful project model

Topvisor uses a stateful hierarchy — unlike stateless rank-check APIs, you first configure a project, then submit checks, then read results:

1. topvisor_add_project { url: "https://example.com" }
   → project_id

2. topvisor_add_searcher { project_id, searcher_key: 0 }
   # 0 = Yandex; 1 = Google

3. topvisor_add_region { project_id, searcher_key: 0, region_key: <catalog_key>, region_depth: 1 }
   # region_key is the Topvisor catalog key, NOT region_index

4. topvisor_list_regions { project_id }
   → region_index (use this, not region_key, in all subsequent calls)

5. topvisor_import_keywords { project_id, group_name: "main", keywords: "name\nкупить окна\nокна цены" }

6. topvisor_check_price { project_id, regions_indexes: [<region_index>] }
   # Preview cost before spending balance

7. topvisor_check_positions { project_id, regions_indexes: [<region_index>] }
   # Async submit — returns projectsIds, does NOT wait for results

8. (poll) topvisor_list_projects { filters: [{name:"id",operator:"EQUALS",values:[project_id]}], fields: ["id","status_positions","positions_percent"] }
   # Wait until status_positions indicates completion

9. topvisor_get_history { project_id, regions_indexes: [<region_index>], date1: "2026-06-01", date2: "2026-06-22" }
   → keywords[] with positionsData

region_key vs region_index

⚠️ These are different values. A common source of errors:

• region_key — the catalog identifier used when adding a region (topvisor_add_region). Comes from the Topvisor regions catalog and differs per search engine.

• region_index — the sequential index assigned by Topvisor after a region is added to your project. This is what topvisor_get_history, topvisor_check_price, topvisor_check_positions, and topvisor_get_snapshots expect.

Always call topvisor_list_regions after adding a region to retrieve the assigned region_index. Do not assume region_key === region_index.

Confirmed live on project 29248320 (green-line24.ru):

Note: region_key=51 for Yandex corresponds to the Yandex rids value for Samara — but this coincidence does not hold in general.

topvisor_list_regions uses get/projects_2/projects with show_searchers_and_regions=2 (the searchers_regions/export endpoint returns CSV with no region_index and is not used).

checker/go is async

topvisor_check_positions submits a job to the Topvisor queue and returns immediately with projectsIds. The actual position collection happens in the background — typically minutes to hours depending on the queue and number of keywords/regions.

How to wait for results:

1. Call topvisor_check_positions → get projectsIds.

2. Poll topvisor_list_projects with fields: ["id","status_positions","positions_percent"] until the status indicates completion.

3. Then call topvisor_get_history to read the collected positions.

There is no built-in wait/poll in this MCP tool (v1). This is intentional — position checks can take hours, which would exceed MCP client timeouts.

Error format

Topvisor API always returns HTTP 200. Errors are indicated in the response body:

{
  "result": null,
  "errors": [
    {
      "code": 53,
      "string": "Authorisation error",
      "detail": { "header": "Authorization" }
    }
  ]
}

Known error codes: 53 = authorization error (wrong/missing credentials); 1002 = parameter value mismatch.

When a tool encounters a Topvisor error, it returns:

{
  "isError": true,
  "errors": [{ "code": 53, "string": "Authorisation error", "detail": {...} }]
}

Known limitations and API quirks

• Rate limits: Topvisor API rate limits are not documented. This server does not implement automatic retries or backoff in v1. If you hit rate limit errors, add delays between calls manually.

• Async checker: topvisor_check_positions does not poll for completion. You must poll topvisor_list_projects yourself.

• Undocumented methods: Several edit/delete methods (edit/projects_2/projects/*, del/keywords_2/keywords, etc.) have undocumented parameters and are not available as typed tools. Use topvisor_request as an escape hatch.

• region_key for specific cities: The Topvisor region catalog uses its own identifiers per search engine. Use topvisor_request with get/positions_2/searchers_regions to browse available regions.

• topvisor_balance: The bank_2/info endpoint returns empty result:[] for single-user accounts regardless of parameters (confirmed: fields causes error 2003, all other params ignored). Balance is computed as sum of bank_2/history transactions.

• topvisor_add_project: Returns a bare integer (project_id), not an object or array.

• topvisor_add_searcher / topvisor_add_region: Return 0 on duplicate add (idempotent, not an error).

• searchers_regions/export: Returns CSV in windows-1251 encoding with no region_index field — not usable for the key→index mapping. Use topvisor_list_regions instead (which calls projects_2/projects with show_searchers_and_regions=2).

License

MIT © 2026 SCom-82