Yandex Wordstat MCP

Yandex Wordstat MCP

Servidor MCP para Yandex Wordstat (Яндекс Вордстат): consulte estatísticas de demanda de busca — frequência, consultas semelhantes, sazonalidade e geografia — a partir de Claude, Cursor, Codex e outros clientes de IA em linguagem natural.

O assistente seleciona as palavras-chave, avalia a demanda e sua dinâmica e compara regiões — algo que, na versão web do Wordstat, exige navegar manualmente por três abas.

_{Sessão MCP real: servidor real, handshake e tools/call via stdio usando o SDK oficial; as respostas do Yandex Cloud Search API (Wordstat) são fixtures gravadas (docs/demo), portanto a demo funciona sem chave e sem rede — vhs docs/demo.tape.}

Início rápido

1. Obtenha a chave da API Yandex Cloud — o mesmo tipo de chave usado para YandexGPT.

2. Adicione o servidor — por exemplo, no Claude Code (outros clientes):

   claude mcp add yandex-wordstat \
     -e WORDSTAT_API_KEY=ваш_ключ -e WORDSTAT_FOLDER_ID=ваш_folder \
     -- npx -y mcp-yandex-wordstat@latest
   

3. Pergunte ao assistente: “Quantas pessoas buscam por 'comprar bicicleta' por mês e quais são as consultas semelhantes?”

O que faz

• Top e consultas semelhantes — top_requests: consultas populares com a frase + semanticamente próximas (associations) e volume total nos últimos 30 dias.
• Dinâmica — dynamics: série {date, count, share} por dias/semanas/meses — sazonalidade e tendência.
• Regiões — regions: distribuição da demanda por regiões com affinityIndex (onde o interesse está acima/abaixo da média); modos all / cities / regions.
• Diretório de regiões — list_regions: árvore id → name para filtros e decodificação de regiões.
• raw_request universal — chamada direta a qualquer caminho da API.
• Yandex Cloud Search API v2 — autenticação, endpoints e esquemas ocultos por trás de ferramentas normalizadas.
• Resiliência — tentativas novamente em 429/5xx com backoff e timeout de solicitação.

Exemplos de consultas

Peça ao assistente em russo — por exemplo:

• “Quantas pessoas buscam por 'comprar bicicleta' por mês e quais são as consultas semelhantes?”
• “Mostre a sazonalidade da demanda por 'esquis' por mês ao longo de um ano”
• “Em quais cidades o interesse por 'entrega de pizza' é maior?”
• “Encontre palavras-chave em torno de 'reforma de apartamentos' com frequência”

Acesso à API

O servidor funciona via Yandex Cloud Search API v2 (host searchapi.api.cloud.yandex.net, autorização com chave de API Yandex Cloud). Os dados do Wordstat são estatísticas públicas agregadas de demanda (não vinculadas a uma conta de anúncios), então uma única chave de API atende todo o servidor. O acesso é self-serve, com a mesma chave do YandexGPT — sem necessidade de solicitações ou campanhas ativas.

A antiga API separada do Wordstat (api.wordstat.yandex.net, OAuth) não está mais disponível. O Yandex transferiu essa funcionalidade para o Yandex Search API na plataforma Yandex Cloud (que é o backend do servidor); apenas a versão web permanece separada em wordstat.yandex.ru. O suporte ao flavor oauth foi removido na versão 2.0.0.

Instalação

claude mcp add yandex-wordstat \
  -e WORDSTAT_API_KEY=ваш_ключ -e WORDSTAT_FOLDER_ID=ваш_folder \
  -- npx -y mcp-yandex-wordstat@latest

/plugin marketplace add askads/claude-plugins
/plugin install yandex-wordstat@askads

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

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

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

Obtendo acesso

1. Crie uma conta de serviço com o papel search-api.webSearch.user e obtenha uma chave de API com escopo yc.search-api.execute — veja a documentação do AI Studio.
2. Descubra o folderId — o ID do catálogo é visível no console Yandex Cloud na página do catálogo (e em sua URL).
3. Registre a chave em WORDSTAT_API_KEY, o catálogo em WORDSTAT_FOLDER_ID.

⚠️ A chave é armazenada em texto puro no config do cliente — trate-a como uma senha.

Configuração

Requisitos

• Node.js 20+ (executado via npx, sem instalação separada).
• Acesso ao Yandex Cloud Search API — veja Obtendo acesso.

Limitações

• Somente leitura. A API do Wordstat não possui operações de modificação — o servidor apenas lê dados.
• Cota compartilhada. O limite (pela cobrança do Yandex Cloud Search API) é calculado por chave, comum a todas as chamadas. Armazene em cache list_regions e respostas por frases, não aumente a frequência.

Documentação

• Todas as ferramentas — lista completa com descrição.
• Desenvolvimento — build, testes, verificação smoke.
• Publicação — release e listagem em diretórios MCP.

Veja também

• Ask Ads — analista de chat e “vigia” de contas de anúncios dos autores deste servidor: alertas sobre vazamentos de orçamento e falhas de rastreamento no Telegram.
• askads/claude-plugins — marketplace de plugins Claude: servidores Ask Ads são instalados com um único comando, tokens são solicitados na ativação.

Suporte

Dúvidas, ideias e melhorias — escreva no Telegram: @gistrec.

Licença

MIT — veja LICENSE.