@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

Configuration

| Environment Variable | Required | Default | Description | |---|---|---|---| | TOPVISOR_USER_ID | yes | — | Your Topvisor User ID (found in account settings) | | TOPVISOR_API_KEY | yes | — | Your Topvisor API key (generate in account settings) | | TOPVISOR_API_URL | no | https://api.topvisor.com/v2/json | Override base URL | | TOPVISOR_HTTP_TIMEOUT_MS | no | 30000 | HTTP request timeout in milliseconds |

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

| Tool | Service | Description | |---|---|---| | topvisor_services | — | List all API services, searcher_key reference, filter operators. Works without credentials. | | topvisor_request | any | Generic escape hatch: call any Topvisor API v2 method directly. | | topvisor_balance | bank_2 | Get account balance computed from transaction history (bank_2/info is non-functional for single-user accounts). | | topvisor_bank_history | bank_2 | Get transaction history (deposits, charges, bonuses). | | topvisor_list_projects | projects_2 | List projects with filtering, ordering, optional searchers/regions. | | topvisor_add_project | projects_2 | Create a new project by URL. | | topvisor_add_searcher | positions_2 | Add a search engine (Yandex/Google/etc.) to a project. | | topvisor_add_region | positions_2 | Add a region to a searcher. See region_key vs region_index below. | | topvisor_list_regions | positions_2 | List configured regions and get their region_index values. | | topvisor_list_keywords | keywords_2 | List keywords in a project. | | topvisor_import_keywords | keywords_2 | Import keywords via CSV (bulk, with group assignment). | | topvisor_check_price | positions_2 | Preview cost of a position check without running it. | | topvisor_check_positions | positions_2 | ASYNC submit a position check job. See checker/go is async below. | | topvisor_get_history | positions_2 | Read position history for a project and regions. | | topvisor_get_summary | positions_2 | Get position summary comparing two dates. | | topvisor_get_summary_chart | positions_2 | Get chart data for position distribution over time. | | topvisor_get_snapshots | snapshots_2 | Get SERP snapshots collected during a position check. |

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):

| City | region_key | region_index | |---|---|---| | Samara | 51 | 83 | | Tolyatti | 240 | 112 | | Zhigulyovsk | 11132 | 829 | | Syzran | 11139 | 557 |

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.

SERP snapshots

SERP snapshots are only collected when a position check is submitted with do_snapshots: 1 (topvisor_check_positions { ..., do_snapshots: 1 }). Snapshots typically become available before the position collection fully completes.

topvisor_get_snapshots returns the snapshot data under the snapshotsData key (not data). Keys have the format "YYYY-MM-DD:position:region_index" and map to objects like:

{
  "snapshotsData": {
    "2026-06-23:1:83": { "url": "https://green-line24.ru/", "domain": "green-line24.ru", "snippet_title": "", "snippet_body": "" }
  }
}

Note: snippet_title / snippet_body are returned but may be empty strings — Topvisor does not always populate them even when requested via positions_fields.

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: ``json { "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