yandex-wiki-search-mcp

English | Русский

Yandex Wiki Search MCP

Claude、Cursor、Windsurf、または任意の MCP クライアントを Yandex Wiki に接続できます。全文検索、 ページ、コメント、添付ファイル、動的テーブル（「グリッド」）に対応し、型付きスキーマを備えた 33 個のツールを提供します。

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

• 🔍 Wiki 全体の全文検索 — Wiki のウェブ検索バーを支えるものと同じバックエンドを使用し、1 回のクエリで最大 50 件の結果を取得できます
• 📄 ページのライフサイクル全体に対応 — 作成、更新、追記（先頭／末尾／アンカー位置）、複製、復元トークンを使った削除、コメント、ファイルのアップロード
• 📊 動的テーブル（グリッド） — 行、列、セル、コピー、並べ替えに対応する 11 個の書き込みツール
• 🔒 サーバー側の読み取り専用モード — WIKI_READ_ONLY=true を設定すると書き込みツールが登録されないため、エージェントが回避することはできません
• 🧩 型付きツールインターフェース — すべてのツールに入力 JSON スキーマと安全性注釈（読み取り専用／破壊的／冪等性のヒント）が付属します。ネイティブ画像またはリソースブロックで応答する page_read_attachment を除き、すべてのツールに出力スキーマも付属します
• 🐳 あらゆる環境で実行可能 — デスクトップクライアント向けの stdio、チーム向けの streamable-http + Docker（オプションのマルチユーザー OAuth に対応）

クイックスタート

1. Wiki へのアクセス権を持つ Yandex OAuth トークン（公式ガイド）と、組織 ID を取得します。
2. クライアントにインストールします。

Claude Desktop のバッジから最新リリースの .mcpb バンドルをダウンロードできます。 ダブルクリックすると Claude Desktop がサーバーをインストールし、トークンと組織 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"}
    }
  }
}

ヒント

まずは WIKI_READ_ONLY=true に設定してください。サーバーには書き込みツールが登録されません。 エージェントに編集を任せてもよいと判断したら、false に切り替えてください。

3. エージェントに質問してみましょう。例は以下をご覧ください。

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

できること

「オンボーディング資料を探して、重要な手順を要約してください。」

「インシデント対応についての資料はありますか？ 最も関連性の高いページを開いてください。」

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

「オンコールのローテーション表に、alice を来週の担当として追加してください。」

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

「下書きページを削除してください。ただし、気が変わったときのために復旧トークンは残してください。」

ツール

33 個のツールがあります。WIKI_READ_ONLY=true の場合、書き込みツールはすべて表示されません。

検索と読み取り（10）

ページ：書き込み（12）

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

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 プラグイン、および Wiki に関する42個の wiki_* ツールを備えた MCP サーバー（読み取り15／書き込み27、注釈付き、--read-only フラグあり）。全文検索ツールはなく、添付ファイルのダウンロードは CLI／SDK のみ

2026年8月時点で、全文検索に対応しているのはこのプロジェクト（最大50件）と slartus（最大10件）のみです。Yandex の公式ホスト型サーバーには検索ツールがありません。また、検索、グリッドへの書き込み、サーバー側の読み取り専用モード、型付きスキーマを組み合わせているのは、このプロジェクトだけです。

このプロジェクトは ya-yandex-wiki-mcp のフォークであり、slartus/mcp-yandex-wiki の調査結果も活用しています — クレジットを参照してください。

全文検索

page_search は POST /v1/search エンドポイントをラップします。Wiki のウェブ検索バーを支えるものと同じバックエンドで、Yandex が 2026 年 8 月に API reference を公開するまで文書化されていませんでした。まず検索し、結果の slug を指定して page_get で開きます。

• 通信モードは 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 で自分の ID を取得でき、「自分の X に関するページを探す」を 2 回の呼び出しで実行できます）、created_between／modified_between（日付の範囲。両方の境界値が必須で、片方を省略すると API に拒否されます）です。
• "exact phrase" のように引用符で囲んだ完全一致フレーズも検索できます。page の結果には https://wiki.yandex.ru/... の絶対 URL が、file の結果には直接ダウンロードリンクが付与されます。
• content は約 510 文字の抜粋で、ページ本文でも要約でもありません。マッチ箇所に応じた位置から切り出されるため、検索語が抜粋内に含まれるとは限りません。また、改行やタブは断片間の区切りではなく、ページ本来のレイアウトを反映しています（表のセルはタブ区切りで返されます）。highlight=true を指定すると、マッチ箇所が <em> タグで囲まれます。ページの内容に基づいて回答する前に、page_get でページを読み込んでください。file の結果では空になります。

ツリーをたどる

page_get_descendants は、あらゆる階層の {id, slug} を含むサブツリーを、1 つのフラットなリストとして返します。page_id／slug の代わりに from_root=true を指定すると、Wiki 全体をたどれます。開始する slug がわからない場合の入口となるため、検索だけが探索方法ではありません。セクションの slug がわかっている場合は、そちらを指定してください。Wiki には数千ページに及ぶものがあり、fetch_all は約 500 件の上限に達すると truncated: true を返して処理を停止します。

検証済みの API 動作に関する追加情報（スコープ、403 の意味、エラー形式、上限）はこちらをご覧ください：docs/api-notes.md。

設定

デプロイ

%%{init: {"flowchart": {"wrappingWidth": 300}}}%%
flowchart LR
    L["Local MCP client<br/>Claude / Cursor /<br/>Windsurf / VS Code<br/>single user"]
    T["Team MCP clients<br/>multi-user,<br/>optional OAuth"]
    S["yandex-wiki-search-mcp"]
    W["Yandex Wiki API"]
    R[("Redis<br/>optional OAuth<br/>token store")]
    L -- "stdio" --> S
    T -- "streamable-http" --> S
    S --> W
    S -.-> R

Docker による HTTP サーバー（MCP エンドポイントは http://localhost:8000/mcp です）：

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

警告

OAUTH_ENABLED=true を設定しない場合、HTTP エンドポイント自体に認証機能はありません。ポートにアクセスできる人なら誰でも、あなたの WIKI_TOKEN を使えます。例ではループバックのみに公開し、他のマシンからのアクセスを防いでいます。また、サーバーはループバックの Host 名にのみ応答するため、名前を 127.0.0.1 に再バインドする Web ページからのアクセスも防ぎます（MCP_ALLOWED_HOSTS を参照）。いずれも認証ではありません。マシン上のプロセスであれば、引き続き使用できます。アクセス範囲を広げる場合は、認証を行うリバースプロキシの背後に置くか、OAuth を有効にしてください。

メモ

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

services:
  mcp-wiki:
    image: ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest  # or: build: .
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      - WIKI_TOKEN=${WIKI_TOKEN}
      - WIKI_ORG_ID=${WIKI_ORG_ID}
      - TRANSPORT=streamable-http
      # Only if another container reaches it as http://mcp-wiki:8000:
      # - MCP_ALLOWED_HOSTS=localhost,127.0.0.1,mcp-wiki
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

• 読み取り専用はサーバー側で適用されます：WIKI_READ_ONLY=true の場合、書き込みツールは登録されません。誤った判断をしたエージェントが呼び出せるものはありません。
• プレーントークンでの HTTP は認証されません：HTTP トランスポートを使用し、OAuth が無効の場合、ポートに到達できるすべての呼び出し元は WIKI_TOKEN の所有者として動作します。エンドポイントの ?orgId=／?cloudOrgId= は設定値より優先されるため、そのトークンがアクセスできる組織すべてが対象です。ループバック上で使用するか、認証プロキシの背後に置くか、OAuth を有効にしてください。ループバックだけでは、ページが自身の名前を 127.0.0.1 に再バインドするケースを防げません。そのため、サーバーはデフォルトでループバックのもののみ、MCP_ALLOWED_HOSTS にある Host 名に応答します。ローカルファイルシステム用ツール（page_upload_attachment、page_download_attachment）は stdio 経由でのみ登録されるため、HTTP サーバーが呼び出し元に代わって自身のディスクを読み書きすることはありません。
• 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

uv は Python 3.11～3.14 の中からインタープリターを選択します。この範囲のバージョンには uv.lock にホイールが用意されています（.python-versions）。マシンに該当するものがない場合はダウンロードします。

コミットする前に、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            # live contract checks
uv run python scripts/contract_sweep.py users/YOU/contract-sweep --cleanup  # remove fixtures

.env に SWEEP_SLUG=users/YOU/contract-sweep を設定すると（.env.example を参照）、slug 引数を省略できます。サーバー自体がこの変数を読み取ることはありません。

API drift check ワークフローは、DRIFT_* リポジトリシークレットが設定されている場合、同じスイープを毎週実行します（手順はワークフローヘッダーに記載されています）。シークレットが設定されていない場合は、何も通知せずスキップします。

クレジット

このプロジェクトは、Yandex Wiki API 用の優れた、十分にテストされた Python MCP サーバーである、Aleksandr Ponkratov による APonkratov/yandex-wiki-mcp（ya-yandex-wiki-mcp）のフォークとして始まりました。ライセンスは Apache-2.0 です。その後、全文検索、33 個すべてのツールに対する型付き入力スキーマと 32 個のツールに対する出力スキーマ、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