English | Русский

Yandex Wiki Search MCP

Verbinde Claude, Cursor, Windsurf oder einen beliebigen MCP-Client mit Yandex Wiki: Volltextsuche, Seiten, Kommentare, Anhänge und dynamische Tabellen ("Grids") — 33 Tools mit typisierten Schemas.

Ein inoffizielles Projekt — weder mit Yandex verbunden noch von Yandex unterstützt.

• 🔍 Volltextsuche im gesamten Wiki — dasselbe Backend, das auch die Wiki-Websuchleiste betreibt, bis zu 50 Ergebnisse pro Abfrage

• 📄 Vollständiger Seitenlebenszyklus — erstellen, aktualisieren, anhängen (oben / unten / Anker), klonen, löschen mit Wiederherstellungs-Token, Kommentare, Datei-Uploads

• 📊 Dynamische Tabellen (Grids) — 11 Schreib-Tools: Zeilen, Spalten, Zellen, kopieren, sortieren

• 🔒 Serverseitiger Nur-Lese-Modus — WIKI_READ_ONLY=true registriert die Schreib-Tools einfach nicht, sodass der Agent es nicht umgehen kann

• 🧩 Typisierte Tool-Oberfläche — jedes Tool liefert Eingabe- und Ausgabe-JSON-Schemas sowie Sicherheitsannotationen (Hinweise auf Nur-Lese-, destruktive und idempotente Operationen)

• 🐳 Läuft überall — stdio für Desktop-Clients, streamable-http + Docker (mit optionalem Multi-User-OAuth) für Teams

Schnellstart

1. Hol dir ein Yandex-OAuth-Token mit Wiki-Zugriff (offizielle Anleitung) und deine Organisations-ID.

2. Installiere es in deinen Client:

Das Badge für Claude Desktop lädt das .mcpb-Bundle der neuesten Version herunter — doppelklicke darauf, und Claude Desktop installiert den Server und fragt nach dem Token und der Organisations-ID (uv muss installiert sein).

{
  "mcpServers": {
    "yandex-wiki-search": {
      "command": "uvx",
      "args": ["yandex-wiki-search-mcp"],
      "env": {
        "WIKI_TOKEN": "YOUR_TOKEN",
        "WIKI_ORG_ID": "YOUR_ORG_ID",
        "WIKI_READ_ONLY": "true"
      }
    }
  }
}

claude mcp add yandex-wiki-search \
  -e WIKI_TOKEN=YOUR_TOKEN -e WIKI_ORG_ID=YOUR_ORG_ID -e WIKI_READ_ONLY=true \
  -- uvx yandex-wiki-search-mcp

{
  "mcpServers": {
    "yandex-wiki-search": {
      "command": "docker",
      "args": ["run","--rm","-i",
        "-e","WIKI_TOKEN","-e","WIKI_ORG_ID","-e","WIKI_READ_ONLY=true",
        "ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest"],
      "env": {"WIKI_TOKEN":"YOUR_TOKEN","WIKI_ORG_ID":"YOUR_ORG_ID"}
    }
  }
}

[!TIP] Starte mit WIKI_READ_ONLY=true — der Server registriert dann nicht einmal Schreib-Tools. Stell es auf false um, sobald du deinem Agenten Bearbeitungen zutraust.

3. Frag deinen Agenten etwas — siehe unten.

Der Server läuft auf dem MCP Python SDK v2. Das ist für Clients unsichtbar — ein einzelner v2-Server beantwortet jede Protokollrevision bis zurück zu 2024-11-05 sowie die aktuelle, du musst also weder auf deiner Seite etwas ändern noch etwas neu installieren.

Der einzige Grund, sich zurückzuhalten, ist eine gemeinsame Umgebung, die mcp<2 für etwas anderes pinnt. 1.0.1 ist die letzte Veröffentlichung, die auf dem 1.x SDK basiert, und bleibt auf PyPI:

pip install "yandex-wiki-search-mcp<1.1"

Related MCP server: mediawiki-mcp-server

Was kann es tun?

"Finde unsere Onboarding-Dokumente und fasse die wichtigsten Schritte zusammen."

"Was haben wir zum Thema Incident Response? Öffne die relevanteste Seite."

"Erstelle eine Seite team/weekly-notes und füge die heutige Standup-Zusammenfassung an."

"Füge eine Zeile zum On-Call-Rotations-Grid hinzu: alice, nächste Woche."

"Lade diese PDF auf die Projektseite hoch und verlinke sie unten."

"Lösche die Entwurfsseite, aber behalte den Wiederherstellungs-Token, falls ich es mir anders überlege."

Tools

33 Tools. Alle Schreib-Tools verschwinden, wenn WIKI_READ_ONLY=true ist.

Suche & Lesen (10)

Seiten: schreiben (12)

Grids: Schreiben (11)

Besonderheiten von Grids:

• Mutationen verwenden optimistisches Sperren – zuerst das Grid abrufen und die neueste revision übergeben.

• grid_update.default_sort akzeptiert Einträge wie [{"column": "status", "direction": "asc"}]; der Server konvertiert sie in das Drahtformat, das die API erwartet.

• grid_add_columns erfordert required für jede Spalte, weil die echte API dies validiert.

• grid_copy gibt Operations-Metadaten zurück, kein fertig kopiertes Grid-Objekt.

Vergleich

Fakten geprüft anhand der Dokumentationen und des veröffentlichten Codes der Alternativen, Juli–August 2026; die Werkzeugliste des offiziellen gehosteten Servers wurde live von mcp.wiki.yandex.net (wiki-mcp-server 1.28.1, 2026-08-11) erfasst.

Auch wissenswert:

• best-doctor/mcp-yandex-wiki (Python) — Seiten erstellen / aktualisieren plus Lesen, mit einem separaten -ro-Schreibschutz-Einstiegspunkt; kein Löschen / Wiederherstellen, keine Grids, keine Suche; nur PyPI

• brekhov-ilya/yandex-wiki-mcp (npm) — Seiten lesen / schreiben / verschieben, Grids schreibgeschützt; interaktiver PKCE-Token-Ablauf mit automatischer Aktualisierung, keine Volltextsuche

• n-r-w/yandex-mcp (Go) — Yandex Tracker + Wiki in einem Server, von Natur aus schreibgeschützt (5 Wiki-Lesewerkzeuge), keine Suche; Authentifizierung nur über IAM-Tokens von der yc-CLI — Yandex-OAuth-Tokens werden nicht unterstützt

• bim-ba/ycli (Python) — ein Toolkit für Tracker + Wiki + Forms: eine CLI, ein Python-SDK, ein Claude-Code-Plugin und ein MCP-Server, dessen Wiki-Oberfläche aus 42 wiki_*-Tools besteht (15 lesen / 27 schreiben, annotiert, mit einem --read-only-Flag); kein Volltextsuchwerkzeug, und Anhang-Downloads bleiben nur CLI/SDK

Stand August 2026 gibt es Volltextsuche nur hier (bis zu 50 Ergebnisse) und bei slartus (bis zu 10) – Yandex' eigener gehosteter Server wird ohne Suchwerkzeug ausgeliefert – und die Kombination aus Suche, Grid-Schreibvorgängen, serverseitigem Schreibschutzmodus und typisierten Schemata ist einzigartig für dieses Projekt.

Dieses Projekt ist ein Fork von ya-yandex-wiki-mcp und baut auf Erkenntnissen aus slartus/mcp-yandex-wiki auf – siehe Credits.

Volltextsuche

page_search kapselt den POST /v1/search-Endpunkt – dasselbe Backend, das die Wiki-Websuchleiste antreibt, undokumentiert, bis Yandex im August 2026 seine API-Referenz veröffentlichte. Zuerst suchen, dann ein Ergebnis mit page_get über dessen slug öffnen.

• Bis zu 50 Ergebnisse pro Aufruf (limit wird auf 1–50 begrenzt; die API lehnt alles andere ab).

• Filter laufen serverseitig, vor dem Limit – eine gefilterte Suche verliert dadurch keine Treffer: slug_prefix (Abschnittsfilter, tiefe Präfixe wie tech-doc/ml sind in Ordnung), result_type (page/file), authors (Seitenbesitzer per uid/cloud_uid – user_get_current liefert Ihre eigenen, wodurch „finde meine Seiten über X“ zu zwei Aufrufen wird) und created_between/modified_between-Datumsintervalle (beide Grenzen erforderlich – die API lehnt offene ab).

• In Anführungszeichen gesetzte "exact phrase"-Suchanfragen funktionieren; page-Ergebnisse erhalten absolute https://wiki.yandex.ru/...-Links, file-Ergebnisse direkte Download-Links.

• content ist ein ~510-Zeichen-Auszug, nicht die Seite und keine Zusammenfassung: Er wird dort abgeschnitten, wo der Treffer sitzt, die Suchbegriffe müssen nicht darin enthalten sein, und seine Zeilenumbrüche und Tabs stammen aus dem Layout der Seite selbst (Tabellenzellen kommen tabulatorgetrennt an) und sind keine Trennzeichen zwischen Fragmenten. Übergeben Sie highlight=true, um Treffer in <em>-Tags eingebettet zu erhalten. Lesen Sie die Seite mit page_get, bevor Sie darauf antworten. Bei file-Ergebnissen leer.

Durchlaufen des Baums

page_get_descendants gibt einen Teilbaum als eine flache Liste von {id, slug} aus jeder Verschachtelungsebene zurück. Wenn Sie from_root=true anstelle von page_id/slug übergeben, wird das gesamte Wiki durchlaufen – der Einstieg, wenn kein Start-Slug bekannt ist, sodass die Suche nicht der einzige Einstiegspunkt ist. Bevorzugen Sie einen Abschnitts-Slug, wenn Sie einen haben: Wikis umfassen Tausende von Seiten, und fetch_all stoppt bei seiner ~500-Elemente-Obergrenze mit truncated: true.

Weiteres verifiziertes API-Verhalten (Scopes, 403-Semantik, Fehlerhüllen, Limits): docs/api-notes.md.

Konfiguration

Mit OAUTH_ENABLED=true wird der Server zu einem OAuth-Anbieter: Jeder MCP-Benutzer autorisiert sich mit seinem eigenen Yandex-Konto, und Anfragen an die Wiki-API werden mit seinem persönlichen Token ausgeführt. page_upload_attachment und page_download_attachment sind in diesem Modus nicht registriert: Sie lesen und schreiben Dateien auf dem Rechner, auf dem der Server läuft – bei einer gemeinsamen Bereitstellung ist das nicht der Rechner des Aufrufers.

Organisation pro Benutzer wählen. WIKI_ORG_ID / WIKI_CLOUD_ORG_ID sind unter OAuth optional, da jede Anfrage ihre eigene Organisation benennen kann: Hängen Sie ?orgId=... (oder ?cloudOrgId=...) an die MCP-Server-URL an, mit der sich Ihr Client verbindet. Ein Abfrageparameter gewinnt gegenüber der serverweiten Einstellung, sodass eine Bereitstellung mehrere Organisationen bedienen kann. Trägt eine Anfrage keines von beiden, schlägt der Werkzeugaufruf mit einer Meldung fehl, die auf beide Optionen verweist – setzen Sie die Umgebungsvariable als Standard, wenn alle Ihre Benutzer eine Organisation teilen.

Siehe .env.example für die vollständige kommentierte Liste und compose.yaml für eine Redis-Basislinie.

Bereitstellung

flowchart LR
    C["MCP client<br/>Claude / Cursor / Windsurf / VS Code"]
    S["yandex-wiki-search-mcp"]
    W["Yandex Wiki API"]
    R[("Redis<br/>optional OAuth token store")]
    C -- "stdio (local, single user)" --> S
    C -- "streamable-http (+ OAuth, multi-user)" --> S
    S --> W
    S -.-> R

HTTP-Server über Docker (der MCP-Endpunkt ist http://localhost:8000/mcp):

docker run --env-file .env -e TRANSPORT=streamable-http -p 8000:8000 \
  --log-opt max-size=10m --log-opt max-file=3 \
  ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest

[!HINWEIS] Der Server schreibt keine eigenen Logdateien – alles geht nach stderr, das der Standard-json-file-Treiber von Docker ohne Größenlimit speichert. Die --log-opt-Flags oben begrenzen das; entfernen Sie sie nur, wenn Ihr Daemon bereits einen Standard festlegt.

services:
  mcp-wiki:
    image: ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest  # or: build: .
    ports:
      - "8000:8000"
    environment:
      - WIKI_TOKEN=${WIKI_TOKEN}
      - WIKI_ORG_ID=${WIKI_ORG_ID}
      - TRANSPORT=streamable-http
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Für Redis-gestützte OAuth-Speicherung verwenden Sie die vorhandene compose.yaml als Basislinie.

Sicherheit

• Schreibgeschützt ist serverseitig: Mit WIKI_READ_ONLY=true werden Schreibwerkzeuge nie registriert – es gibt nichts, was ein verwirrter Agent aufrufen könnte.

• Die Wiki-API erzwingt keine OAuth-Scopes (erneut verifiziert am 11.08.2026, nachdem Yandex die Scopes dokumentiert hat – siehe docs/api-notes.md): Ein wiki:read-Token kann trotzdem schreiben, verwenden Sie also den schreibgeschützten Modus, statt sich auf Token-Scopes zu verlassen.

• Geheimnisse sind durchgängig SecretStr – in Logs und repr maskiert; DEBUG-HTTP-Protokollierung enthält niemals Header oder Bodies.

• Löschen ist wiederherstellbar: page_delete gibt ein Wiederherstellungs-Token für page_recover zurück.

• Nicht zusammenhängende Schlüssel in einer gemeinsamen .env werden ignoriert, aber eine falsch geschriebene Einstellung (WIKI_READ_ONL) stoppt den Server, statt stillschweigend auf einen Standard zurückzufallen, den Sie nicht gewählt haben.

Entwicklung

uv sync --dev
uv run yandex-wiki-search-mcp   # run locally
uv run pytest                   # tests

Führen Sie vor dem Committen die vollständige Verifikationssuite aus CONTRIBUTING.md aus. Wie der Server aufgebaut ist – die Schichten, die Codekarte, Testnähte, CI und der Release-Prozess – wird in docs/architecture.md beschrieben. Verifiziertes API-Verhalten und Prüfskripte sind in docs/api-notes.md dokumentiert.

Die Wiki-API driftet (der Such-Endpunkt hat seinen Vertrag bereits einmal stillschweigend geändert, als er noch undokumentiert war) — scripts/contract_sweep.py überprüft jede Client-Methode erneut gegen eine Live-Organisation und meldet Validierungsabweichungen und nicht deklarierte Schlüssel:

uv run python scripts/contract_sweep.py users/YOU/contract-sweep            # ~30 live checks
uv run python scripts/contract_sweep.py users/YOU/contract-sweep --cleanup  # remove fixtures

Der Workflow API drift check führt denselben Sweep wöchentlich aus, wenn die Repository-Secrets DRIFT_* konfiguriert sind (Anweisungen im Workflow-Header); ohne sie wird er stillschweigend übersprungen.

Danksagungen

Dieses Projekt begann als Fork von APonkratov/yandex-wiki-mcp (ya-yandex-wiki-mcp) von Aleksandr Ponkratov, einem hervorragenden, gut getesteten Python-MCP-Server für die Yandex-Wiki-API, lizenziert unter Apache-2.0. Es hat inzwischen eine eigene API-Oberfläche entwickelt — Volltextsuche, typisierte Eingabe- und Ausgabeschemata über alle 33 Tools, YFM-Helfer, Cursor-Draining, Multi-User-OAuth und einen Live-Contract-Sweep gegen die API — , während das ursprüngliche Urheberrecht und die ursprüngliche Lizenz erhalten bleiben (siehe LICENSE und NOTICE).

Die Idee und die zentralen API-Erkenntnisse hinter der Volltextsuche stammen von slartus/mcp-yandex-wiki (JavaScript, MIT): Es war das erste, das den damals undokumentierten Endpunkt POST /v1/search entdeckte (eine Referenz dafür veröffentlichte Yandex erst im August 2026) und meldete, dass OAuth-Scopes nicht erzwungen werden. Es wurde kein Code übernommen — nur Erkenntnisse und Ideen, die unabhängig gegen eine Live-Organisation verifiziert und hier erweitert wurden.

Markenzeichen

„Yandex“ und „Yandex Wiki“ sind Markenzeichen von YANDEX LLC. Dies ist ein inoffizielles, von der Community erstelltes Projekt, das nicht mit Yandex verbunden ist, nicht von Yandex gesponsert wird und keine Unterstützung von Yandex erhält — die Namen werden hier rein nominativ verwendet, um zu bezeichnen, mit welchem Dienst der Server spricht. Das Logo ist ein eigenständiges Zeichen, das weder das Yandex-Wiki- noch das MCP-Branding übernimmt (Design-Notizen).

mcp-name: io.github.dlbolshov/yandex-wiki-search-mcp