Yandex Search API

Servidor MCP Yandex Search.API

Servidor MCP para a API de Busca Yandex via REST com 7 ferramentas:

• web_search
• image_search
• generative_search
• wordstat_get_top
• wordstat_get_dynamics
• wordstat_get_regions_distribution
• wordstat_get_regions_tree

O servidor lê as credenciais da configuração de ambiente do cliente MCP:

• FOLDER_ID
• API_KEY

Para desenvolvimento local, .env é carregado automaticamente.

Recursos

• Usa apenas endpoints REST (/v2/web/search, /v2/image/search, /v2/gen/search, caminhos REST do Wordstat)
• Entradas mínimas das ferramentas por padrão para manter o contexto do modelo compacto
• searchType está disponível para todas as ferramentas relevantes e o padrão é SEARCH_TYPE_COM
• A busca na web sempre força responseFormat: FORMAT_XML
• As ferramentas de web/imagem decodificam rawData de Base64 e analisam XML em grupos estruturados
• Tratamento de erros com status e detalhes claros da API

Instalação

npm install yandex-searchapi-mcp

Exemplo de configuração do cliente MCP

{
  "mcpServers": {
    "yandex-searchapi": {
      "command": "npx",
      "args": ["-y", "yandex-searchapi-mcp"],
      "env": {
        "FOLDER_ID": "your-folder-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}

Ferramentas

web_search

Use esta ferramenta quando precisar de resultados clássicos de busca na web (links + trechos), não uma resposta gerada.

Entradas:

• query (obrigatório)
• searchType (opcional, padrão SEARCH_TYPE_COM)
• page (opcional)
• docsOnPage (opcional)
• familyMode (opcional)
• fixTypoMode (opcional)

Retorna:

• groups[] com documents[] onde cada documento contém:
  • url
  • title
  • language
  • passages
• requestId
• found

Observação: para busca na web, esta entrada é mapeada para groupSpec.groupsOnPage na API upstream.

image_search

Use esta ferramenta quando precisar de resultados de busca de imagens e metadados de imagens (links de miniatura/original e dimensões).

Entradas:

• query (obrigatório)
• searchType (opcional, padrão SEARCH_TYPE_COM)
• page (opcional)
• site (opcional)
• docsOnPage (opcional)
• imageSpec (opcional: format, size, orientation, color)

Retorna:

• groups[] com documents[] onde cada documento contém:
  • url
  • extras.image-properties (se presente)
• requestId
• found

generative_search

Use esta ferramenta quando precisar de uma resposta fundamentada e pronta para uso, sintetizada a partir dos resultados da busca.

Entradas:

• query (obrigatório)
• searchType (opcional, padrão SEARCH_TYPE_COM)
• fixMisspell (opcional)
• getPartialResults (opcional)
• scope (opcional): { type: "site" | "host" | "url", values: string[] }

Retorna apenas os campos generativos principais (sem objetos wrapper):

• message
• sources
• searchQueries
• fixedMisspellQuery
• isAnswerRejected
• isBulletAnswer
• hints
• problematicAnswer

wordstat_get_top

Use esta ferramenta para entender quais consultas relacionadas os usuários pesquisam em torno de uma palavra-chave.

Entradas:

• phrase (obrigatório)
• numPhrases (opcional, padrão 20)
• regions (opcional)
• devices (opcional)

Retorna:

• totalCount
• results
• associations

wordstat_get_dynamics

Use esta ferramenta para acompanhar tendências de demanda ao longo do tempo para uma palavra-chave.

Entradas:

• phrase (obrigatório)
• period (opcional, padrão PERIOD_WEEKLY)
• fromDate (opcional, padrão now-30d, data/hora ISO)
• toDate (opcional, padrão now, data/hora ISO)
• regions (opcional)
• devices (opcional)

Retorna:

• results

wordstat_get_regions_distribution

Use esta ferramenta para ver em quais regiões/cidades uma palavra-chave é relativamente mais popular.

Entradas:

• phrase (obrigatório)
• region (opcional, padrão REGION_ALL)
• devices (opcional)

Retorna:

• results

wordstat_get_regions_tree

Use esta ferramenta para obter IDs e nomes de regiões válidos para filtros regionais do Wordstat.

Entradas:

• nenhuma

Retorna:

• regions

Desenvolvimento

npm install
npm run build
npm run dev