Yandex Search.API MCP-Server

MCP-Server für die Yandex Search API über REST mit 7 Tools:

• web_search

• image_search

• generative_search

• wordstat_get_top

• wordstat_get_dynamics

• wordstat_get_regions_distribution

• wordstat_get_regions_tree

Der Server liest Anmeldedaten aus der MCP-Client-Umgebungskonfiguration:

• FOLDER_ID

• API_KEY

Für die lokale Entwicklung wird .env automatisch geladen.

Funktionen

• Verwendet nur REST-Endpunkte (/v2/web/search, /v2/image/search, /v2/gen/search, Wordstat REST-Pfade)

• Minimale Tool-Eingaben standardmäßig, um den Modellkontext kompakt zu halten

• searchType ist für alle relevanten Tools verfügbar und standardmäßig auf SEARCH_TYPE_COM gesetzt

• Die Websuche erzwingt immer responseFormat: FORMAT_XML

• Web-/Bild-Tools dekodieren rawData aus Base64 und parsen XML in strukturierte Gruppen

• Fehlerbehandlung mit klarem API-Status und Details

Installation

npm install yandex-searchapi-mcp

Beispiel für MCP-Client-Konfiguration

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

Tools

web_search

Verwenden Sie dieses Tool, wenn Sie klassische Websuchergebnisse (Links + Snippets) benötigen, keine generierte Antwort.

Eingaben:

• query (erforderlich)

• searchType (optional, Standard SEARCH_TYPE_COM)

• page (optional)

• docsOnPage (optional)

• familyMode (optional)

• fixTypoMode (optional)

Rückgabewerte:

• groups[] mit documents[], wobei jedes Dokument Folgendes enthält:

  • url

  • title

  • language

  • passages

• requestId

• found

Hinweis: Bei der Websuche wird diese Eingabe auf groupSpec.groupsOnPage in der Upstream-API abgebildet.

image_search

Verwenden Sie dieses Tool, wenn Sie Bildsuchergebnisse und Bildmetadaten (Miniaturansicht/Original-Links und Abmessungen) benötigen.

Eingaben:

• query (erforderlich)

• searchType (optional, Standard SEARCH_TYPE_COM)

• page (optional)

• site (optional)

• docsOnPage (optional)

• imageSpec (optional: format, size, orientation, color)

Rückgabewerte:

• groups[] mit documents[], wobei jedes Dokument Folgendes enthält:

  • url

  • extras.image-properties (falls vorhanden)

• requestId

• found

generative_search

Verwenden Sie dieses Tool, wenn Sie eine gebrauchsfertige, fundierte Antwort benötigen, die aus Suchergebnissen synthetisiert wurde.

Eingaben:

• query (erforderlich)

• searchType (optional, Standard SEARCH_TYPE_COM)

• fixMisspell (optional)

• getPartialResults (optional)

• scope (optional): { type: "site" | "host" | "url", values: string[] }

Gibt nur die generativen Kernfelder zurück (ohne Wrapper-Objekte):

• message

• sources

• searchQueries

• fixedMisspellQuery

• isAnswerRejected

• isBulletAnswer

• hints

• problematicAnswer

wordstat_get_top

Verwenden Sie dieses Tool, um zu verstehen, nach welchen verwandten Suchanfragen Nutzer im Zusammenhang mit einem Keyword suchen.

Eingaben:

• phrase (erforderlich)

• numPhrases (optional, Standard 20)

• regions (optional)

• devices (optional)

Rückgabewerte:

• totalCount

• results

• associations

wordstat_get_dynamics

Verwenden Sie dieses Tool, um Nachfragetrends für ein Keyword im Zeitverlauf zu verfolgen.

Eingaben:

• phrase (erforderlich)

• period (optional, Standard PERIOD_WEEKLY)

• fromDate (optional, Standard now-30d, ISO-Datum)

• toDate (optional, Standard now, ISO-Datum)

• regions (optional)

• devices (optional)

Rückgabewerte:

• results

wordstat_get_regions_distribution

Verwenden Sie dieses Tool, um zu sehen, in welchen Regionen/Städten ein Keyword relativ beliebter ist.

Eingaben:

• phrase (erforderlich)

• region (optional, Standard REGION_ALL)

• devices (optional)

Rückgabewerte:

• results

wordstat_get_regions_tree

Verwenden Sie dieses Tool, um gültige Regions-IDs und Namen für regionale Wordstat-Filter zu erhalten.

Eingaben:

• keine

Rückgabewerte:

• regions

Entwicklung

npm install
npm run build
npm run dev