English | Русский

Yandex Wiki Search MCP

Claude、Cursor、Windsurf、または任意のMCPクライアントを Yandex Wiki に接続できます: 全文検索、 ページ、コメント、添付ファイル、動的テーブル（"grids"）— 型付きスキーマを持つ 33のツール。

非公式プロジェクトです。Yandex とは提携しておらず、Yandex の承認も受けていません。

• 🔍 全文検索 — Wiki全体を検索対象。Wiki の Web 検索バーを支えているのと同じバックエンドを使用し、クエリあたり最大50件の結果を返します。

• 📄 ページライフサイクル全体 — 作成、更新、追記（先頭 / 末尾 / アンカー）、複製、リカバリートークン付き削除、コメント、ファイルのアップロード

• 📊 動的テーブル（grids） — 書き込みツール11件: 行、列、セル、コピー、並べ替え

• 🔒 サーバーサイドの読み取り専用モード — WIKI_READ_ONLY=true に設定すれば書き込みツールを登録すらしないため、エージェントに回避されません。

• 🧩 型付きツールサーフェス — すべてのツールに、入力と出力のJSONスキーマと安全性の注釈（読み取り専用 / 破壊的 / 冪等のヒント）が付属します。

• 🐳 どこでも実行可能 — デスクトップクライアントにはstdio、チームには（オプションのマルチユーザーOAuth付き）streamable-http + Docker

クイックスタート

1. Wiki アクセス権限りを持つ Yandex Ｏ OAuthトークン（公式ガイd）と、自分の組織IDを取得します。

2. 使用中のクライアントにインストールします:

[](https://cursor.com/install-mcp?name=yandex-wiki-search\\\\&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ5YW5kZXgtd2lraS1zZWFyY2gtbWNwIl0sImVudiI6yJXSUtJfT1PS6OuVDRS6UWnInWhI 77

Claude Desktop のバッジからは最新リリースの .mcpb バンドルがダウンロードされます。 ダブルクリックするとClaude Captainが方式stable がンデルインストールされ、トークンと 組織IDの入力を求めます（uv がインストールされている必要があります）。

{
  "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] 最初は WIKI_READ_ONLY=true で試してみましょう — サーバーは書き込みツールを登録すらしません。 エージェントが編集を行っても信頼できるようになったら false に切り替えます。

3. 次は、エージェントに何か依頼してみましょう — 以下の例をどうぞ。

サーバーはMCP Python SDK v2 で動作しています。これはクライアントから見えません — v2 の 1サーバーで、2024-11-05 まで遡るすべてのプロトコルリビジョンと現在のリビジョンの両方に 応答できるため、あなた側で変更する必要も再インストールする必要もありません。

古いSDKに留まる理由があるとすれば、他の何かのために mcp<2 を固定している共存環境がある場合だけです。 1.0.1 は1.x SDK でビルドされた最後のリリースで、PyPI に残っています:

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

Related MCP server: mediawiki-mcp-server

できること

「オンボーディングのドキュメントを見つけて、主要な手順を要約してください。」

「インシデント対応について何かありますか? 最も関連するページを開いてください。」

「team/weekly-notes というページを作成して、今日のスタンドアップ要約を追記してください。」

「オンコール当番表（grid）に行を1つ追加してください: alice、来週。」

「このPDFをプロジェクトページにアップロードして、末尾にリンクしてください。」

「下書きのページを削除してください。ただし、後で設定を変えと思う場合のためにリカバリートークンは残してください。」

ツール

33 のツール。WIKI_READ_ONLY=true にすると、書き込みツールはすべて使えなくなります。

検索と読み取り (10)

ページ: 書き込み (12)

グリッド: 書き込み（11）

グリッドの仕様:

• 変更操作は楽観ロックを使用する — まずグリッドを取得し、最新の revision を渡す。

• grid_update.default_sort は [{"column": "status", "direction": "asc"}] のエントリを受け取る。サーバーが API の想定するワイヤフォーマットに変換してくれる。

• grid_add_columns は各列に required が必須である。実 API が必須として検証するため。

• grid_copy はコピー済みの完成したグリッドオブジェクトではなく、操作メタデータを返す。

代替実装との比較

事実は、2026 年7〜8月の時点で、代替実装のドキュメントと公開コードで検証した。 公式のホスト型サーバーのツール一覧は、mcp.wiki.yandex.net （wiki-mcp-server 1.28.1、2026-08-11）からライブで取得した。

参考までに、他にも次の実装があります。

• best-doctor/mcp-yandex-wiki (Python) — ページの作成/更新と読み取りが可能で、別途 -ro 読み取り専用エントリポイントもあります。削除/復元・グリッド・検索は未対応。PyPI のみ。

• brekhov-ilya/yandex-wiki-mcp (npm) — ページの読み取り/書き込み/移動、グリッドは読み取り専用。自動更新付きの対話的な PKCE トークンフロー。全文検索はありません。

• n-r-w/yandex-mcp (Go) — Yandex Tracker と Wiki を1つのサーバーに統合し、設計上読み取り専用（Wiki 読み取りツール5つ）。検索なし。認証は yc CLI の IAM トークン限定で、Yandex OAuth トークンは対象外です。

• bim-ba/ycli (Python) — Tracker・Wiki・Forms をまとめたキットです。CLI、Python SDK、Claude Code プラグインを備え、MCP サーバーの Wiki 側は42個の wiki_* ツール群（読み取り15 / 書き込み27、注釈付き、--read-only フラグあり）。全文検索ツールはなく、添付ファイルのダウンロードは CLI/SDK のみです。

2026年8月現在、全文検索を実現するのは本プロジェクト（最大50件）と slartus（最大10件）だけで、Yandex 公式のホスト型サーバーには検索ツールがありません。加えて、検索・グリッド書き込み・サーバー側読み取り専用モード・型付き出力スキーマの4つをすべて備えるのは本プロジェクトだけです。

このプロジェクトは ya-yandex-wiki-mcp のフォークであり、slartus/mcp-yandex-wiki の知見をもとに作られています。謝辞 を参照してください。

全文検索

page_search は POST /v1/search エンドポイントのラッパーです。Wiki の検索バーが使う同じバックエンドで、Yandex が 2026年8月の API リファレンス を公開するまで非公開でした。まず検索し、その結果を page_get に slug を渡して開きます。

• 2つの通信モードがあります。デフォルトでは: 1回の呼び出しで最大 50 件（limit は1〜50にクランプされ、それ以外の値はAPIが拒否）、ページです。レスポンスのカーソルは常に null。highlight=true のときは、ページ結果が limit に関係なく10件までですし、一致箇所は <em> で囲まれます。cursor（next_cursor に戻るページ番号）で約100件まで戻ります。 results が空になるか、空でないページで next_cursor が null になるまで続きます。末尾を過ぎても next_cursor は空ページを数えるため、それ自体が「まだある」ことにはなりません。

• フィルターはサーバー側で limit の前に実行されます。条件付き検索でも、limit によって該当結果が失われません。slug_prefix（セクションフィルター。tech-doc/ml のような深いプレフィックスも可）、result_type（page/file）、authors（uid/cloud_uidによるページ所有者。user_get_current が自己の情報を返すため、「自分のXに関するページ」が呼び出し2回で済みます）、created_between/modified_between の日付範囲（両端必須。APIは開いた範囲を拒否します）。

• 引用符 "exact phrase" のクエリが動作します。pageの結果には絶対 URL のhttps://wiki.yandex.ru/...` リンク、file の結果には 直接ダウンロードリンクが返ります。 *content は 約510文字の抜粿 で、ページ本文でも要約でもありません。一致箇所を起点に切り取られるため、内容にクエリー語が含されているとも限りません。改行・タブは 断片の区切りではなく、ページ元のレイアウトです（表セルはタブ区切りで届きます）。一致を <em> で囲むには highlight=true を指定します。その内容を答に使む前に、page_get で本ペー지를読んでください。file の結果ではこの項目は空です。

ツーリーの走査

page_get_descendants は、サブツリーを1つのフニートな {id, slug} リストとして返します。 page_id / slug の代わりに from_root=true を渡すと Wiki 全体 を走査できます。た、検索だけがエントリではなく、開始 slug} が不明な場合に利用できます。セクション slug を指定できる場合はそちらをしてください。Wikiにま数多くのページが存在し、fetch_all は約500項目の上限に達すると truncated: true を返し停止します。

検証済みのAPI動作（スコープ、403の意味、エラーエンベロープ、制限）については、docs/api-notes.md を参照してください。

設定

OAUTH_ENABLED=true の場合、サーバーは OAuth プロバイダーになります。各 MCP ユーザーは自分の Yandex アカウントで認証し、Wiki API へのリクエストは個人のトークンで行われます。このモードでは page_upload_attachment と page_download_attachment は登録されません。これらはサーバーが稼働しているマシン上のファイルを読み書きするものであり、共有デプロイメントではそのマシンは呼び出し元のマシンではありません。

ユーザーごとのオーガニゼーションの選択。 OAuth では WIKI_ORG_ID / WIKI_CLOUD_ORG_ID はオプションです。各リクエストでオーガニゼーションを指定できるためです。クライアントが接続する MCP サーバー URL に ?orgId=...（または ?cloudOrgId=...）を追加してください。クエリパラメーターはサーバー全体の設定よりも優先されるため、1つのデプロイメントで複数のオーガニゼーションを利用できます。リクエストがどちらも指定しない場合、ツール呼び出しは両方のオプションを示すメッセージで失敗します。すべてのユーザーが共通のオーガニゼーションを持つ場合は、環境変数を既定値として設定してください。

完全な注釈付きリストは .env.example を、Redis のベースラインは compose.yaml を参照してください。

デプロイメント

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

Docker 経由の HTTP サーバー（MCP エンドポイントは 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

[!NOTE] このサーバーは独自のログファイルを書きません。すべては stderr に出力され、Docker の既定の json-file ドライバーは サイズ制限を設けずに保存します。上記の --log-opt フラグで上限を設定します。デーモンがすでに既定値を設定している場合のみ、それらフラグを省略してください。

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"

Redis バックエンドの OAuth ストレージには、既存の compose.yaml をベースラインとして使用してください。

セキュリティ

• 読み取り専用はサーバーサイドで実施: WIKI_READ_ONLY=true の場合、書き込みツールは決して登録されません。混乱したエージェントが呼び出せるものは何もありません。

• Wiki API は OAuth スコープを強制しないこと（Yandex がスコープを文書化した後、2026-08-11 に再検証済み — docs/api-notes.md を参照）: wiki:read トークンでも書き込みはできるため、トークンのスコープに頼らず読み取り専用モードを使用してください。

• シークレットはすべて SecretStr です — ログと repr ではマスクされます。DEBUG HTTP ログにヘッダーや本文が含まれることはありません。

• 削除は復元可能です: page_delete は page_recover のための復元トークンを返します。

• 共有 .env 内の無関係なキーは無視されますが、タイプミスの設定（WIKI_READ_ONL）は、選択していない既定値に黙ってフォールバックする代わりに、サーバーを停止させます。

開発

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

コミットする前に、CONTRIBUTING.md の完全な検証セットを実行してください。 サーバーがどのように構成されているか（レイヤー、コードマップ、テストの結合点、CI、リリースプロセス）は docs/architecture.md に説明されています。 検証済みの API 動作とプローブスクリプトは docs/api-notes.md に文書化されています。

Wiki API は仕様が漂移（ドリフト）します（検索エンドポイントは、ドキュメント化される前の時期に一度、静かに契約を変更しています） — scripts/contract_sweep.py は、すべてのクライアントメソッドを実環境の組織に対して再検証し、検証不一致や未宣言キーを報告します。

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

API ドリフトチェック ワークフローは、DRIFT_* リポジトリシークレットが設定されている場合に、同じスイープを毎週実行します（手順はワークフローのヘッダーにあります）。シークレットがなければ、静かにスキップします。

クレジット

このプロジェクトは、APonkratov/yandex-wiki-mcp（ya-yandex-wiki-mcp）のフォークから始まりました。作者は Aleksandr Ponkratov 氏で、Yandex Wiki API 向けの優れたテスト済み Python MCP サーバーであり、Apache-2.0 でライセンスされています。それ以来、このプロジェクトは独自のサーフェスを拡大してきました。全文検索、33 ツールすべてにわたる型付き入力 および 出力スキーマ、YFM ヘルパー、カーソルドレイン、マルチユーザー OAuth、API に対するライブ契約スイープを備えています。一方、元の著作権とライセンスは保持されています（LICENSE と NOTICE を参照）。

全文検索の背後にあるアイデアと主要な API の発見は、slartus/mcp-yandex-wiki（JavaScript、MIT）に由来します。そこは、当時ドキュメント未整備だった POST /v1/search エンドポイントを初めて発見し（Yandex がそのリファレンスを公開したのは 2026 年 8 月になってからです）、OAuth スコープが強制されていないことも報告しました。このプロジェクトはそこからコードを一切取っておらず、発見とアイデアだけを取り入れて、実環境の組織に対して独立に再検証し、ここで拡張しています。

商標

「Yandex」および「Yandex Wiki」は YANDEX LLC の商標です。本プロジェクトは非公式のコミュニティ制作物であり、Yandex との提携・協賛・承諾は一切ありません。これらの名称は、サーバーが通信するサービスを指すために用名的に使用されています。ロゴはオリジナルのマークであり、Yandex Wiki や MCP のブランドを再現したものではありません（デザインノート）。

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