Яндекс Вордстат MCP

Яндекс Вордстат MCP connects an AI application to Yandex search demand statistics. Ask how often a phrase is searched, in which months interest grows, and in which cities the topic is more popular — the assistant will collect Wordstat data and explain the result. The server works through Yandex Cloud Search API, so it does not require access to the Direct advertising account.

• Five tools. Top and similar queries, demand dynamics, regional distribution, region reference, and a technical API request.

• Read-only. The Wordstat API does not create campaigns, ads, key phrases, or other objects.

• Demand and seasonality. Top queries and regions show the last 30 days; dynamics are built by day, week, or month for the desired period.

• Region and device. Reports can be narrowed to a region and compare demand on computers, phones, and tablets.

• No Direct OAuth. You need an API key and a Yandex Cloud folder ID for Search API.

Start with a safe request:

How many times a month is "buy a bike" searched, and what similar queries are there?

Connect the server · See scenarios · Open technical documentation

See it work in a minute

Related MCP server: yandex-searchapi-mcp

Contents

• Quick start

• What you can delegate

• How to read demand data

• How to get access

• What can change the data

• Data, limits, and background work

• Technical documentation

• Support

Quick start

You need Node.js 20 or newer, a Yandex Cloud API key for Search API, and a Yandex Cloud folder ID.

1. Get access and add the server to your AI application — instructions for five applications below.

2. Ask: "How many times a month is 'buy a bike' searched, and what similar queries are there?"

Through the application interface:

1. Open Settings → Plugins → MCP servers.

2. Click Add server.

3. Add the launch command npx -y mcp-yandex-wordstat@latest and environment variables WORDSTAT_API_KEY, WORDSTAT_FOLDER_ID.

Through the command line:

codex mcp add yandex-wordstat \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  -- npx -y mcp-yandex-wordstat@latest

Check the connection:

codex mcp list

Official Codex instructions

claude mcp add \
  --env WORDSTAT_API_KEY=ваш_ключ \
  --env WORDSTAT_FOLDER_ID=ваш_folder_id \
  --transport stdio \
  --scope user \
  yandex-wordstat \
  -- npx -y mcp-yandex-wordstat@latest

Check the server:

claude mcp list

Claude Code documentation

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

If Edit Config is unavailable, edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.

For all projects, create ~/.cursor/mcp.json; for the current project only, create .cursor/mcp.json:

{
  "mcpServers": {
    "yandex-wordstat": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "ваш_ключ",
        "WORDSTAT_FOLDER_ID": "ваш_folder_id"
      }
    }
  }
}

Cursor documentation

Open the command palette and run MCP: Open User Configuration. Add to mcp.json:

{
  "servers": {
    "yandex-wordstat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-wordstat@latest"],
      "env": {
        "WORDSTAT_API_KEY": "${input:wordstat_api_key}",
        "WORDSTAT_FOLDER_ID": "${input:wordstat_folder_id}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "wordstat_api_key",
      "description": "API-ключ Yandex Cloud",
      "password": true
    },
    {
      "type": "promptString",
      "id": "wordstat_folder_id",
      "description": "ID каталога Yandex Cloud"
    }
  ]
}

Check the launch with the MCP: List Servers command.

VS Code documentation

What you can delegate

Find and evaluate demand

• "How many times a month is this phrase searched, and what similar queries appear?"

• "Find queries around 'pizza delivery' with their frequency."

• "Show queries containing my phrase separately from semantically similar ones."

Understand seasonality

• "Show demand for 'skis' by month for a year."

• "In which weeks does demand for this service grow or fall?"

• "Compare the dynamics of a query on phones and computers."

Compare regions

• "In which cities is interest in 'apartment renovation' above average?"

• "Compare demand in Moscow and St. Petersburg."

• "Find the ID of the needed region and narrow the next report to it."

How to read demand data

top_requests shows popular queries that contain the given phrase and semantically close queries. The overall totalCount refers to the last 30 days.

dynamics returns a series {date, count, share} with daily, weekly, or monthly granularity. regions distributes demand over the last 30 days by region, and an affinityIndex above 100% means above-average interest. Counter values may come as strings: Yandex passes large integers in JSON in this form.

One call builds data for only one phrase. For a large list of keywords, it is better to first narrow the list rather than run all queries in a row: the Yandex Cloud Search API quota is shared for one key.

How to get access

1. In Yandex Cloud, create a service account with the role search-api.webSearch.user.

2. Issue an API key for it with the scope yc.search-api.execute — the steps are described in the AI Studio documentation.

3. Find the folder ID (folderId) in the Yandex Cloud console on the folder page and in the page URL.

4. Pass the key as WORDSTAT_API_KEY and the folder as WORDSTAT_FOLDER_ID.

The server accesses Yandex Cloud Search API v2. The old separate Wordstat API with OAuth is not used. The API key is stored in plain text in the MCP client configuration — treat it like a password.

What can change the data

Nothing in Яндекс Вордстат. All five tools, including raw_request, work read-only. Technically, the API uses POST, but Wordstat has no write endpoints; the server additionally does not allow an arbitrary request to go to another host.

Data, limits, and background work

• Aggregated data. The server receives search demand statistics, not data from a specific advertising account.

• Region reference cache. In a long-lived process, the region tree is loaded once and reused in subsequent requests.

• Retries on temporary errors. The timeout for one request is 60 seconds. The server makes up to three retries after 429, 5xx, a network error, or a timeout; it respects Retry-After, and the delay does not exceed 30 seconds.

• No background monitoring. The server works when the AI application calls it. If the application supports scheduled tasks, you can set up a periodic report for selected phrases there.

• Anonymous telemetry. By default, the server sends a random installation ID, the event or tool name, server, Node.js, OS, and AI client versions. It does not include the API key, tool arguments, your messages, demand data, or environment variable values. To disable it for Ask Ads MCP servers: ASKADS_TELEMETRY=0.

Technical documentation

• MCP capabilities catalog — pages on user tasks for each tool.

• All tools and parameters

• Development documentation

• Publishing documentation

• Yandex Cloud Search API documentation

Support

Found a bug or missing a scenario? Create an issue or write to Telegram.