Yandex Wordstat MCP

Yandex Wordstat MCP

Yandex Wordstat MCP conecta um aplicativo de IA às estatísticas de demanda de busca do Yandex. Pergunte com que frequência uma frase é pesquisada, em quais meses o interesse cresce e em quais cidades o tema é mais popular — o assistente coletará os dados do Wordstat e explicará o resultado. O servidor funciona por meio da Yandex Cloud Search API, portanto não requer acesso à conta de publicidade do Direct.

• Cinco ferramentas. Principais e consultas semelhantes, dinâmica de demanda, distribuição por regiões, diretório de regiões e consulta técnica à API.
• Somente leitura. A API do Wordstat não cria campanhas, anúncios, frases-chave ou outros objetos.
• Demanda e sazonalidade. Os principais termos e regiões mostram os últimos 30 dias; a dinâmica é construída por dias, semanas ou meses para o período desejado.
• Região e dispositivo. Os relatórios podem ser restritos a uma região e comparar a demanda em computadores, celulares e tablets.
• Sem OAuth do Direct. São necessários uma chave de API e o ID do catálogo do Yandex Cloud para a Search API.

Comece com uma consulta segura:

Quantas vezes por mês pesquisam por “comprar bicicleta” e quais são as consultas semelhantes?

Conectar servidor · Ver cenários · Abrir documentação técnica

Veja o funcionamento em um minuto

Conteúdo

• Início rápido
• O que você pode pedir
• Como ler os dados de demanda
• Como obter acesso
• O que pode alterar os dados
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

São necessários Node.js 20 ou superior, uma chave de API do Yandex Cloud para a Search API e o ID do catálogo do Yandex Cloud.

1. Obtenha acesso e adicione o servidor ao aplicativo de IA — instruções para cinco aplicativos abaixo.
2. Pergunte: “Quantas vezes por mês pesquisam por ‘comprar bicicleta’ e quais são as consultas semelhantes?”

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

codex mcp list

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

claude mcp list

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

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

{
  "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"
    }
  ]
}

O que você pode pedir

Selecionar e avaliar a demanda

• “Quantas vezes por mês pesquisam essa frase e quais consultas semelhantes aparecem?”
• “Selecione consultas em torno de ‘entrega de pizza’ com suas frequências.”
• “Mostre consultas que contenham minha frase, separadas das semanticamente semelhantes.”

Entender a sazonalidade

• “Mostre a demanda por ‘esquis’ por mês ao longo de um ano.”
• “Em quais semanas a demanda por esse serviço cresce ou cai?”
• “Compare a dinâmica da consulta em celulares e computadores.”

Comparar regiões

• “Em quais cidades o interesse por ‘reforma de apartamentos’ está acima da média?”
• “Compare a demanda em Moscou e São Petersburgo.”
• “Encontre o ID da região desejada e restrinja o próximo relatório a ela.”

Como ler os dados de demanda

top_requests mostra as consultas populares que contêm a frase fornecida e consultas semanticamente próximas. O totalCount geral refere-se aos últimos 30 dias.

dynamics retorna uma série de {date, count, share} com detalhamento diário, semanal ou mensal. regions distribui a demanda dos últimos 30 dias por regiões, e um affinityIndex acima de 100% significa interesse acima da média. Os valores dos contadores podem vir como strings: o Yandex envia números inteiros grandes em JSON dessa forma.

Uma única chamada gera dados apenas para uma frase. Para uma lista grande de palavras-chave, é melhor primeiro reduzir a lista, em vez de executar todas as consultas em sequência: a cota da Yandex Cloud Search API é compartilhada para uma mesma chave.

Como obter acesso

1. No Yandex Cloud, crie uma conta de serviço com a função search-api.webSearch.user.
2. Emita uma chave de API para ela com o escopo yc.search-api.execute — as etapas estão descritas na documentação do AI Studio.
3. Encontre o ID do catálogo (folderId) no console do Yandex Cloud na página do catálogo e no URL da página.
4. Passe a chave como WORDSTAT_API_KEY e o catálogo como WORDSTAT_FOLDER_ID.

O servidor acessa a Yandex Cloud Search API v2. A antiga API separada do Wordstat com OAuth não é usada. A chave de API é armazenada em texto simples na configuração do cliente MCP — trate-a como uma senha.

O que pode alterar os dados

Nada no Yandex Wordstat. Todas as cinco ferramentas, incluindo raw_request, funcionam somente em leitura. Tecnicamente, a API usa POST, mas o Wordstat não tem endpoints de escrita; o servidor também não permite que uma consulta arbitrária vá para outro host.

Dados, limites e trabalho em segundo plano

• Dados agregados. O servidor recebe estatísticas de demanda de busca, não dados de uma conta de publicidade específica.
• Cache do diretório de regiões. Em um processo de longa duração, a árvore de regiões é carregada uma vez e reutilizada nas próximas consultas.
• Repetições em erros temporários. O tempo limite de uma consulta é de 60 segundos. O servidor faz até três repetições após 429, 5xx, erro de rede ou tempo limite; considera Retry-After, e o atraso não excede 30 segundos.
• Sem monitoramento em segundo plano. O servidor funciona quando é chamado pelo aplicativo de IA. Se o aplicativo suportar tarefas agendadas, você pode configurar um relatório periódico para as frases selecionadas.
• Telemetria anônima. Por padrão, o servidor envia um identificador aleatório de instalação, nome do evento ou ferramenta, versões do servidor, Node.js, SO e cliente de IA. Não inclui chave de API, argumentos de ferramentas, suas mensagens, dados de demanda ou valores de variáveis de ambiente. Para desativá-la para servidores MCP do Ask Ads: ASKADS_TELEMETRY=0.

Documentação técnica

• Catálogo de recursos MCP — páginas sobre tarefas de usuário para cada ferramenta.
• Todas as ferramentas e parâmetros
• Documentação de desenvolvimento
• Documentação de publicação
• Documentação da Yandex Cloud Search API

Suporte

Encontrou um erro ou falta um cenário? Crie uma issue ou escreva no Telegram.