🇬🇧 English · 🇷🇺 Русский

Topvisor MCP

Keep your keyword research and ranking history in the conversation.

MCP server for Topvisor: saved rankings, keyword inventory, AI-answer tracker and quoted, budget-capped paid rank checks.

Ask your assistant to inspect a project, prepare keyword groups or find queries that lost positions in saved reports. Topvisor MCP connects those tasks to your existing projects, with previews before supported changes are applied.

Quick start · Connect your assistant · Issues

Try asking your assistant:

Compare saved rankings for my project on two dates I choose. Identify queries that lost positions and group them by target URL.

What you can do

Ranking reports and paid-check walkthrough includes requests, local configuration and recovery from an uncertain launch.

Related MCP server: MCP DataForSEO Server

Why this MCP

• Optional lazy tool loading: set TOPVISOR_TOOL_LOADING=lazy (or choose it in the setup wizard) to start with a small core and enable toolsets on demand; see Lazy tool loading.

• Reads use saved data and are free; a paid check needs topvisor_balance → topvisor_check_quote → confirmation, within operator-set project and cost limits.

• Toolsets (meta, positions, ai_tracker, checks, setup_write) and read-only mode; writes are previewed before they are applied.

• Ranking comparisons and exports keep missing values distinct from ranks (JSON/CSV).

• Other Topvisor MCP servers on GitHub (SCom-82/topvisor-mcp, psilon2000/topvisor-mcp) have no CI workflow; psilon2000 guards writes with confirm=true but has no price quote or budget cap.

Lazy tool loading

Optional lazy tool loading: TOPVISOR_TOOL_LOADING=lazy starts with a small core plus topvisor_enable_toolsets and adds toolsets on demand (tools/list_changed). Startup cost (tools/list + instructions, ≈chars/4): eager ≈5561 tokens, lazy ≈1196 tokens (−78%). Default eager is unchanged; if your client ignores tools/list_changed, keep eager or reconnect after enabling. Scope: enablement is per MCP session (FastMCP session visibility), so one client's enabled toolsets never appear for another. The HTTP transport here is stateless (every request is its own session), so enabled toolsets do not persist there: for shared HTTP use eager or TOPVISOR_TOOLSETS.

Clients and notifications/tools/list_changed (verified against official docs, changelogs or maintainer statements, 2026-10):

Maintained and up to date

• Actively maintained by ZAI.ONE: current version 0.6.1; release notes in CHANGELOG.md and Releases.

• Built-in update check: ask the assistant to run topvisor_check_update (public GitHub API, no credentials, cached; nothing is installed automatically; TOPVISOR_DISABLE_UPDATE_CHECK=1 turns it off).

• Follows current MCP practice: tool annotations (read-only / destructive hints), toolsets and read-only mode, server instructions, prompts and resources, structured errors with recovery hints, secrets kept out of tool output, a token budget for tool descriptions enforced in tests.

• CI runs the test suite on Linux and Windows for every pull request.

Quick start

Prefer a ready package? Install the release and generate your client configuration. No source checkout is required.

Install Python 3.12–3.14 and uv. Clone with Git or download the ZIP. With a ZIP, open the extracted directory and skip the first two commands.

You need your Topvisor user ID and API key. The wizard saves the key in a private local file.

git clone https://github.com/zai-one/topvisor-mcp.git
cd topvisor-mcp
uv sync --frozen
uv run --frozen python scripts/configure.py
uv run --frozen topvisor-mcp --config mcp.local.json --check-config

The wizard creates a local configuration and stores secrets in private files. It refuses to overwrite an existing setup. --check-config validates local settings; the first request below checks your account connection.

Connect your assistant

Add this configuration to an MCP client that uses mcpServers, such as Claude Desktop or Cursor. Replace /ABSOLUTE/PATH/ with your absolute path; Windows JSON paths can use forward slashes, such as D:/Tools/.

{
  "mcpServers": {
    "topvisor": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/topvisor-mcp",
        "run",
        "--frozen",
        "topvisor-mcp",
        "--config",
        "/ABSOLUTE/PATH/topvisor-mcp/mcp.local.json"
      ]
    }
  }
}

The client starts the MCP server for you. Refresh its tool list, then make your first request. For clients with a different config format, reuse the same command and args; uv must be available to the client process.

First request

List my Topvisor projects. For the project I choose, show its search regions and keyword groups.

You should see your projects and their existing settings. You can then request saved positions or prepare a keyword change. A preview does not change project data.

If tools do not appear, check the absolute path, whether the client can find uv, and the --check-config result. For access errors, check account credentials and permissions. Installation and troubleshooting.

Install in your agent

Run topvisor-mcp straight from GitHub with uv. Pin a release tag (@vX.Y.Z) for reproducible installs; placeholders below are examples, keep secrets in files outside the repo.

Claude Code

claude mcp add topvisor --env TOPVISOR_USER_ID=123456 --env TOPVISOR_API_KEY_FILE=/path/to/topvisor.token --env TOPVISOR_STATE_PATH=/path/to/topvisor.sqlite -- uvx --from git+https://github.com/zai-one/topvisor-mcp@v0.6.1 topvisor-mcp

Skills for Claude Code: copy skills/* into ~/.claude/skills/ (or install this repo as a plugin — it ships .claude-plugin/plugin.json with the skills and the MCP server).

Cursor — .cursor/mcp.json (one-click install):

{
  "mcpServers": {
    "topvisor": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/zai-one/topvisor-mcp@v0.6.1",
        "topvisor-mcp"
      ],
      "env": {
        "TOPVISOR_USER_ID": "123456",
        "TOPVISOR_API_KEY_FILE": "/path/to/topvisor.token",
        "TOPVISOR_STATE_PATH": "/path/to/topvisor.sqlite"
      }
    }
  }
}

Codex — ~/.codex/config.toml (skills: copy skills/* into ~/.codex/skills/, or keep the repo's .agents/skills link):

[mcp_servers.topvisor]
command = "uvx"
args = ["--from", "git+https://github.com/zai-one/topvisor-mcp@v0.6.1", "topvisor-mcp"]
env = { TOPVISOR_USER_ID = "123456", TOPVISOR_API_KEY_FILE = "/path/to/topvisor.token", TOPVISOR_STATE_PATH = "/path/to/topvisor.sqlite" }

Claude Desktop — claude_desktop_config.json: the same mcpServers block as Cursor.

Skills (agent playbooks)

Each skill is a self-contained folder skills/<name>/ (SKILL.md + its own references/, templates/); copy the folder and it works. Agents load the short SKILL.md only when the task matches and open the other files on demand. Clients without skills get the same flows as MCP prompts and the topvisor://playbook / topvisor://guide/{topic} resources.

Toolsets and read-only mode

Default: meta, positions, ai_tracker, checks, setup_write. Opt-in: semantics (topvisor_semantics_tools, topvisor_semantics_price, topvisor_semantics_launch: keyword collection, frequency checks, relevance checks, indexing requests, dedupe, clustering progress), analytics (topvisor_report: positions summary/chart, TOP snapshots, competitors, tasks, audit/indexing/watcher, apometr, bank history) and competitors_write (topvisor_competitors_write). Paid topvisor_semantics_launch calls and competitor writes return an approval_id and an operator_command; the operator accepts it outside MCP with topvisor-approval --path STATE_DB --approval-id ID --digest D --accept (or --config with the server's settings file; single use, bound to the account, Topvisor user, caller and exact request incl. project, 30 min, stored in the state database), then the agent repeats the call with approval_id. Paid semantics launches count against TOPVISOR_CHECK_DAILY_BUDGET together with paid rank checks; a launch with an unknown outcome blocks further paid tasks for the project until topvisor-check-reconcile --check-id TASK_ID, and a replay of the same approval returns the stored receipt. Competitor writes use the persistent idempotency ledger (an unconfirmed write stays pending, a repeat returns the stored result). Paid rank checks (topvisor_check_launch) keep the existing quote → approved_cost + confirm_cost=true gate without an approval_id. TOPVISOR_TOOLSETS=default, all or a comma list (see topvisor://toolsets); TOPVISOR_TOOLS=a,b adds single tools, TOPVISOR_DISABLED_TOOLS=a,b removes them, TOPVISOR_READ_ONLY=1 removes every write/paid tool.

Competitor add uses one url per call, with optional name, brand_name, service_name (positions / aiTracker) and brand_aliases. For example: topvisor_competitors_write(action="add", project_id=7, url="example.org", name="Example"). Legacy urls/names accept one item each; multiple items and conflicting scalar/array values are refused before approval. Use brand_name, never brand_names. Prepare a fresh approval after upgrading.

Example requests

• Покажи мои проекты Topvisor и регионы проекта X.

• Сделай недельный отчёт по позициям проекта X (без платных проверок).

• Сколько стоит обновить позиции по проекту X? Запусти только после моего OK.

• Какие запросы выпали из ТОП-10 за неделю?

• Как бренд виден в AI-ответах по сравнению с конкурентами?

• Собери еженедельный SEO-отчёт клиенту.

Access and limits

Ranking reports read history already saved in Topvisor. Paid checks use a separate quote and confirmation workflow, disabled until the operator sets project and estimate limits. Keyword changes default to a preview. Deletion is unavailable; history uses project region indexes. Limits and reconciliation.

Updates

topvisor_check_update compares the installed version with the latest GitHub release and returns the release link and the matching uv tool install --force ... command. It never installs anything. The result is cached for 24 hours next to the state database; when a newer release is cached, the server instructions mention it once. Set TOPVISOR_DISABLE_UPDATE_CHECK=1 to turn off both the tool's network request and the startup refresh.

Authenticated HTTP is available for a server deployment. See HTTP setup, configuration and permissions and Python package integration.

uv sync --frozen --all-groups
uv run --frozen python scripts/verify.py
uv run --frozen python scripts/verify_install.py

Tests use synthetic fixtures. A passing test run does not establish live provider connectivity.

Built by ZAI.ONE

ZAI.ONE is a digital agency working on websites, SEO, advertising and analytics. We also build tools that connect AI assistants to everyday work. Talk to us on Telegram about setup, automation or an integration for your team.

License, use and contributing

• Use: you may install and use this MCP server freely for yourself and your organisation, including commercial work. If it helps, please consider giving the repository a ⭐ — appreciated, never required.

• Contribute: issues and pull requests are welcome; see CONTRIBUTING.md. Never post tokens, cookies, sessions or account data.

• Not allowed without written permission from ZAI.ONE: copying code into other projects, forking for redistribution, embedding the server in other products or offering it as a competing service.

• License: LicenseRef-ZAI-ONE 2.0 (source-available, not open source). Third-party notices and license history: NOTICE.