mcp-yandex-webmaster

Яндекс Вебмастер MCP

Яндекс Вебмастер MCP conecta aplicativos de IA — Claude, Cursor, Codex e outros — aos dados do Yandex Webmaster. Pergunte em linguagem natural como o site aparece na busca do Yandex: quais páginas entraram ou não entraram na busca, o que está acontecendo com impressões e cliques, quais problemas o Webmaster vê, como estão estruturados o sitemap e os links externos. A conexão começa direto no diálogo: não é necessário criar token antecipadamente ou editar configurações.

• 20 ferramentas. Sites, diagnóstico, consultas de busca, indexação, sitemap, links externos e conexão da conta direto do diálogo.
• Funciona com busca orgânica. Não é Metrica, não é Wordstat e não é painel de anúncios: aqui não há dados de tráfego, demanda de busca ou publicidade.
• Conexão no chat. O Yandex abrirá a página de login; o código de uso único é válido por 10 minutos, e o servidor verificará o acesso aos sites imediatamente após a conexão.
• Quase tudo é leitura. Ferramentas específicas podem adicionar um site ou sitemap, iniciar a confirmação de direitos ou colocar uma página na fila de reindexação.
• Apenas seus sites. O servidor vê os dados dos sites aos quais o token tem acesso; para estatísticas e diagnóstico, os direitos sobre o site devem ser confirmados no Webmaster.

Experimente com a primeira mensagem:

Quais problemas críticos o diagnóstico vê agora no meu site?

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

Veja o funcionamento em um minuto

Você: Mostre meus sites no Webmaster e avalie brevemente o estado deles.

Assistente: Mostra os sites disponíveis pelo token, seu IKS, o número de páginas na busca e de páginas excluídas, além da quantidade de problemas por gravidade.

Você: Quais problemas críticos existem no site principal e o que verificar primeiro?

Assistente: Analisa o diagnóstico atual do Webmaster, separa problemas críticos de recomendações e explica quais exigem ações no site.

Você: Por quais consultas o site apareceu com mais frequência na última semana?

Assistente: Mostra consultas com impressões, cliques e posições médias. Se necessário, compara a dinâmica para computadores e dispositivos móveis.

Conteúdo

• Início rápido
• O que pode ser delegado
• Como funciona
• O que pode alterar dados
• Conexão e configuração
• Dados e telemetria
• Limitações
• Documentação técnica
• Suporte

Início rápido

É necessário Node.js 20+. npx baixará o servidor na primeira execução — não é preciso instalar o pacote separadamente. Não é necessário obter token antecipadamente: a conexão ocorre direto no diálogo.

1. Adicione o servidor ao seu aplicativo de IA. Escolha a instrução abaixo.
2. Escreva: «Conecte o Yandex Webmaster» — o assistente conduzirá o login no Yandex e verificará se vê seus sites.
3. Faça a primeira pergunta, por exemplo: «Quais problemas críticos o diagnóstico vê agora no meu site?»

Para CI e instalações automáticas, é possível definir um token pronto — veja Conexão e configuração.

codex mcp add yandex-webmaster \
  -- npx -y mcp-yandex-webmaster@latest

claude mcp add --transport stdio --scope user \
  yandex-webmaster -- npx -y mcp-yandex-webmaster@latest

{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}

{
  "mcpServers": {
    "yandex-webmaster": {
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}

{
  "servers": {
    "yandex-webmaster": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yandex-webmaster@latest"]
    }
  }
}

O que pode ser delegado

Entender o estado do site na busca

• «Mostre meus sites no Webmaster e seus IKS».
• «Quantas páginas do site principal estão na busca e quantas estão excluídas?»
• «Quais problemas críticos e fatais existem no site?»
• «Quais páginas importantes mudaram o status de indexação?»

Analisar consultas de busca

• «Por quais consultas o site apareceu com mais frequência na última semana?»
• «Como mudaram impressões, cliques e posição média do site no último mês?»
• «Compare a visibilidade do site em dispositivos móveis e computadores».

Verificar rastreamento, sitemap e links externos

• «Mostre quais erros HTTP o robô do Yandex encontrou ao rastrear o site».
• «Há erros no sitemap e quando o robô o leu pela última vez?»
• «Mostre exemplos de links externos para o site».

Preparar uma ação no site

• «Verifique se o sitemap https://example.com/sitemap.xml, foi adicionado e explique o que mudará ao adicioná-lo».
• «Quantas reindexações restam hoje para o site e posso enviar uma página para a fila?»
• «Como confirmar os direitos sobre um novo site via DNS?»

Como funciona

O trabalho começa pela lista de sites. Cada um tem um identificador técnico host_id — o servidor o captura da sua solicitação ou da variável YANDEX_WEBMASTER_HOST_ID, se definida.

Após a confirmação dos direitos sobre o site, o servidor pode reunir em um único diálogo:

• estado na busca — IKS, número de páginas na busca e excluídas, problemas atuais;
• visibilidade por consultas — impressões, cliques e posições médias por datas e tipos de dispositivo;
• rastreamento e indexação — códigos HTTP no rastreamento, status de páginas importantes, sitemap e fila de reindexação;
• perfil de links — exemplos de páginas que apontam para o seu site.

Se não houver direitos sobre o site, o Webmaster retornará HOST_NOT_VERIFIED. Se o site ainda não foi carregado ou indexado, HOST_NOT_LOADED e HOST_NOT_INDEXED significam que ainda não há dados, e não indicadores zerados.

O que pode alterar dados

A maioria das perguntas ao servidor apenas lê dados. As seguintes operações alteram o estado no Yandex Webmaster:

As ferramentas que alteram o estado são marcadas para o aplicativo de IA como ações, e raw_request com possível exclusão — como potencialmente irreversível. O aplicativo pode solicitar confirmação, mas o comportamento depende do cliente específico. Para exclusão, é necessária uma solicitação explícita.

Conexão e configuração

O servidor acessa a Yandex Webmaster API v4 em nome da sua conta Yandex e vê os mesmos sites disponíveis para essa conta na interface web do Webmaster.

Para uso comum, não é necessário token antecipadamente:

1. No chat, peça para conectar o Yandex Webmaster.
2. Abra o link do Yandex OAuth com a conta que tem acesso aos sites desejados no Webmaster.
3. Confirme o acesso e envie o código exibido ao assistente. O código é de uso único, válido por 10 minutos e é trocado por token apenas dentro do servidor em execução — não é preciso reiniciar o aplicativo nem editar configurações.

O servidor usa PKCE: o código do chat não pode ser trocado por token por conta própria, portanto enviá-lo no chat é seguro. O token obtido é armazenado localmente em ~/.config/mcp-yandex-webmaster/credentials.json com permissões apenas para o proprietário (0600). A conexão segue funcionando sozinha: o acesso é renovado automaticamente e não expira após um ano. Para verificar o estado — peça «mostre o status da conexão»; para desconectar — «desconecte o Webmaster»; o acesso concedido pode ser revogado no Yandex ID.

Para CI e instalações não padronizadas, há configuração por variáveis de ambiente:

Um token pronto para YANDEX_OAUTH_TOKEN pode ser obtido assim: crie um aplicativo em oauth.yandex.ru, nas permissões escolha API Yandex Webmaster e obtenha o token conforme a instrução do Yandex OAuth. Esse mesmo aplicativo serve para o login pelo diálogo — defina o ClientID dele em YANDEX_WEBMASTER_OAUTH_CLIENT_ID (Redirect URI — https://oauth.yandex.ru/verification_code).

Não publique o token em chats, repositórios ou capturas de tela: ele dá acesso aos sites da sua conta.

Dados e telemetria

Por padrão, o servidor envia eventos técnicos anônimos: identificador aleatório da instalação, nome da ferramenta chamada, versões do servidor, do aplicativo de IA, do Node.js e do sistema operacional. O token Yandex, dados da conta, argumentos das ferramentas, textos das solicitações, valores e nomes de variáveis de ambiente não são enviados.

Para desativar a telemetria dos servidores MCP da Ask Ads, defina a variável de ambiente:

ASKADS_TELEMETRY=0

Limitações

• Direitos confirmados são obrigatórios para estatísticas. Sem eles, estão disponíveis a lista de sites e a verificação do status dos direitos, mas não diagnóstico, consultas e indexação.
• O re-rastreamento é limitado pela cota diária do site. Na resposta há quota_remainder — o restante para hoje. Com 429 QUOTA_EXCEEDED esperar não ajuda: a cota será restaurada amanhã.
• Consultas populares são limitadas pelos dados do Webmaster. No topo entram até 3.000 consultas da última semana, e em uma única consulta é possível obter até 500 linhas.
• Repetições de consultas são previstas apenas para erros temporários. O servidor faz até três tentativas para limites de frequência comuns; erros de rede e servidor são repetidos apenas na leitura, para não duplicar a ação.
• Não há monitoramento contínuo. O servidor funciona quando é chamado pelo aplicativo de IA. Se o aplicativo suportar tarefas agendadas, é possível configurar uma consulta periódica ao servidor para verificar as métricas desejadas.

Documentação técnica

• Todos os instrumentos — parâmetros, respostas e exemplos de chamadas.
• Desenvolvimento — estrutura do projeto e trabalho com o código-fonte.
• Pacote no npm.
• Documentação da API Yandex Webmaster — fonte primária sobre a API e suas limitações.

Suporte

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