English | Русский

Yandex Wiki Search MCP

Подключайте Claude, Cursor, Windsurf или любой другой MCP-клиент к Yandex Wiki: полнотекстовый поиск, страницы, комментарии, вложения и динамические таблицы («grids») — 33 инструмента с типизированными схемами.

Неофициальный проект — не аффилирован с Yandex и не одобрен им.

• 🔍 Полнотекстовый поиск по всей вики — тот же бэкенд, что стоит за строкой поиска в веб-версии Wiki, до 50 результатов на запрос

• 📄 Полный жизненный цикл страниц — создание, обновление, добавление (top / bottom / anchor), клонирование, удаление с recovery-токеном, комментарии, загрузка файлов

• 📊 Динамические таблицы (grids) — 11 инструментов для записи: строки, столбцы, ячейки, копирование, сортировка

• 🔒 Режим только чтения на стороне сервера — при WIKI_READ_ONLY=true инструменты записи просто не регистрируются, поэтому агент не сможет его обойти

• 🧩 Типизированные инструменты — каждый инструмент поставляется с JSON-схемами входа и выхода, а также с аннотациями безопасности (подсказки read-only / destructive / idempotent)

• 🐳 Работает где угодно — stdio для десктопных клиентов, streamable-http + Docker (с опциональным multi-user OAuth) для команд

Быстрый старт

1. Получите OAuth-токен Yandex с доступом к Wiki (официальное руководство) и 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"}
    }
  }
}

[!TIP] Начните с WIKI_READ_ONLY=true — сервер даже не зарегистрирует инструменты записи. Переключите его на false, когда доверите агенту редактирование.

3. Попросите агента решить задачу — примеры ниже.

Сервер работает на MCP Python SDK v2. Для клиентов это незаметно — один сервер v2 отвечает всем ревизиям протокола, вплоть до 2024-11-05, а также актуальной, поэтому вам не нужно ничего менять или переустанавливать.

Единственная причина остаться на старой версии — общая среда, в которой зафиксирован 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 и добавь к ней сегодняшнюю стену-сводку».

«Добавь строку в таблицу дежурств: alice, на следующей неделе».

«Загрузи этот PDF на страницу проекта и добавь ссылку на него внизу».

*«Удали черновик страницы, но сохрани recovery-токен на случай, если я передумаю“.»

Инструменты

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 года; список инструментов официального размещённого сервера получен напрямую с mcp.wiki.yandex.net (wiki-mcp-server 1.28.1, 2026-08-11).

Pages: клонирование в новый slug с помощью page_clone | ✅ page_clone | ❌ | ❌ | ❌ | ✅ |

Стóit ещё знать:

• [best-doctor/mcp-andex-Wiki] (https://github.com/best-/bocuments...) (Python) — page: create / update plus reads, with a separate read-only entry point; no delete/recover, no grids, no search; PyPI only

• [brekhov-ilya/andex-iki-mcp] (https://github...) (JavaScript) — page read / write / move, tables read-only; interactive PKCE toe-token flow with auto-refresh; no full-text search

• [n-r-w/ya-wiki-mcp] (https://github...) — Yandex Tracker + Wiki in a single Go file? Actually it's Go: "Gо" — Yandex Tracker + Wiki в одном сервере, GO doesn't matter; designed as read-only (5 wiki read tools), no search; authorized only via IMA tokens from the yc CLI — direct OAuth for Yandex not supported

• [bim-ba/ya-wiki-mcp] (https://github...) — Go bещs? Actually Python: "Pи-тоно" — One таольkit for Tracker + Wiki + Forms: CLI, Python SDK, Claude Code plugin and MCP server whose Wiki surface is 42 wiki_* tool (15 read / 27 write, annotations, with flag --read-only); no full-text search tool, attachments download remain only CLI/SDK-only

As of August 2026, full-text search exists only here (up to 50 results) and in /slartus/ (up to 10) — Yandex’s official hosted service still does not include search tool — and the combination of search, table writes, server-side read-only mode and typed schemas is unique to this project.

This project is a fork of ya-yandex-wiki-mcp and builds on findings from slartus/mcp-yandex-wiki — see Credits.

Full-text search

page_search wraps the POST /v1/search endpoint — the same backend that powers the Wiki web search, undocumented until Yandex published its API reference in August 2026. Seach first, then open a result with page_get by its slug.

• Two wire modes. By default: up to 50 results in one call (limit is clamped by the server to 1–50; the API rejects anything else) and no pagination — the response cursors are always null. With highlight=true: pages are limited to 10 results regardless of limit, matches come wrapped in <em>, and cursor (the page number echoed back in next_cursor) walks up to ~100 results. The set ends when results comes back empty or next_cursor is null on a non-empty page — past the end next_cursor keeps counting up over empty pages, so it alone does not mean “more exists”.

• Interactive server-side filters run before the limit — a filtered search does not lose matches to it: slug_prefix (section filter, deep prefixes like tech-doc/ml are fine), result_type (page/file), authors (page owners by uid/cloud_uid — user_get_current supplies your own, turning “find my pages accountable about X” into two calls), and created_between/modified_between date intervals (both bounds required — the API rejects open ones).

• Quoted "exact phrase" queries work; page results get absolute https://wiki.yandex.ru/... links, file results get direct download links.

• content is a ~510-character excerpt, not the page and not a summary: it is cut from wherever the match sits, the query terms need not be inside it, and its line breaks and tabs are the page’s own layout (table cells arrive tab-separated) rather than separators between fragments. Pass highlight=true to get matches wrapped in ``tags. Read the page with page_get before answering from it. Empty for file results.

Traversing the tree

page_get_descendants (да, it’s) returns a subtree as one flat list of {id, slug} from every nesting level. Passing from_root=true instead of page_id/slug walks the whole Wiki — the way in when no starting slug is known, so search is not the only entry point. Preer a section slug when you have one: wikis run to thousands of pages, and fetch_all stops at its **~500-item cap with truncated: true.

More verified API behavior (scopes, 403 semantics, error envelopes, limits): docs/api-notes.md.

Configuration

При OAUTH_ENABLED=true сервер становится OAuth-провайдером: каждый пользователь MCP авторизуется под своей учётной записью Yandex, а запросы к Wiki API выполняются с его персональным токеном. В этом режиме инструменты page_upload_attachment и page_download_attachment не регистрируются: они читают и записывают файлы на той машине, где запущен сервер, а при общем развертывании это не машина пользователя, вызывающего инструменты.

Выбор организации для каждого пользователя. WIKI_ORG_ID / WIKI_CLOUD_ORG_ID при OAuth необязательны, потому что каждый запрос может указать свою организацию: добавьте ?orgId=... (или ?cloudOrgId=...) к URL MCP-сервера, к которому подключается ваш клиент. Параметр запроса имеет приоритет над общесерверной настройкой, поэтому одно развертывание может обслуживать несколько организаций. Если в запросе нет ни того, ни другого, вызов инструмента завершается ошибкой с сообщением, указывающим оба варианта. Если все ваши пользователи используют одну организацию, задайте переменную окружения как значение по умолчанию.

Полный аннорированный список переменных см. в .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

HTTP-сервер в Docker (эндпоинт 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"

Для хранения OAuth-токенов в Redis используйте существующий compose.yaml как базовый вариант.

Безопасность

• Режим только для чтения реализован на сервере: при WIKI_READ_ONLY=true инструменты записи вообще не регистрируются — агенту просто нечего будет вызвать.

• Wiki API не соблюдает OAuth-scopes (перепроверено 2026-08-11, после того как Yandex документировал scopes — см. docs/api-notes.md): даже токен wiki:read может записывать, поэтому используйте режим только для чтения, а не полагайтесь на scopes токена.

• Секреты задаются через SecretStr и всегда маскируются в логах и в repr; при уровне DEBUG никогда не логируются заголовки и тела запросов.

• Удаление обратимо: 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. Подтверждённое поведение Wiki API и пробные скрипты задокументированы в docs/api-notes.md.

API «Yandex Wiki» дрейфует (поисковый эндпоинт уже однажды молча изменил контракт, ещё когда тот был недокументирован) — scripts/contract_sweep.py заново проверяет каждый метоd клиента протива живой organization и сообщает о расхождениях валидации и незадекларированных ключах:

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 на дрейф] (.github/workflows/api-drift.yml) запускает ту же проверку еженедельно, когда настроены секреты репозитория DRIFT_* (инструкции — в шапке файла workflow); без них он тихо пропускается.

Благодарности

Этот проekt начался как форк APonkratov/yandex-wiki-mcp (ya-yandex-wiki-mcp) Александра Понкратова — отличного, хорошо протестированного Python MCP-сервера для API Yandex Wiki, распространяемого под лицензией Apache-2.0. С тех пор у него выросла собственная поверхность: полнотекстовый поиск, типизированные схемы входных и выходных данных во всех 33 инструментах, YFM-хелперы, выгрузка по курсорам, многопользовательский OAuth и живая проверка контракта против API, — при этом исходные авторские права и лицензия сохранены (см. LICENSE и NOTICE).

Идея и ключевые находки по API, лежащие в основе полнотекстового поика, пришли из проекта slartus/mcp-yandex-wiki (JavaScript, MIT): именно он первым обнаружил тогда ещё недокументированную POST /v1/search (Yandex опубликовал справку for it only в авусте 2026 годa) and сообщил, что OAuth-скоупе не применяются. Никакого кода от него не было взято — только находки и идеи, незавиником перепроверинные на живой organization и расширенные здесь.

Товарные знаки

«Yandex» и «Yandex Wiki» — товарные знаки YANDEX LLC. Это неофициальный проект, созданный сообщством: он не аффfiliрован с Yandex, не спонсортся им и не одобрен Yandex — названия использются жито в назывной функции, чтобы указать, с какim сервером обрщается сервер. Логотип — оригинальный знак, не воспроизводящий фирменный стиль ни Yandex Wiki, ни MCP (заметки о дизайне).

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