English | Русский

Yandex Wiki Search MCP

Connect Claude, Cursor, Windsurf, or any MCP client to Yandex Wiki: full-text search, pages, comments, attachments, and dynamic tables ("grids") — 27 tools with typed schemas.

• 🔍 Full-text search across the entire wiki — the same backend that powers the Wiki web search bar, up to 50 results per query
• 📄 Full page lifecycle — create, update, append (top / bottom / anchor), clone, delete with a recovery token, comments, file uploads
• 📊 Dynamic tables (grids) — 11 write tools: rows, columns, cells, copy, sort
• 🔒 Server-side read-only mode — WIKI_READ_ONLY=true simply doesn't register write tools, so the agent can't bypass it
• 🧩 Typed tool surface — every tool ships input and output JSON schemas plus safety annotations (read-only / destructive / idempotent hints)
• 🐳 Runs anywhere — stdio for desktop clients, streamable-http + Docker (with optional multi-user OAuth) for teams

Quick start

1. Get a Yandex OAuth token with Wiki access (official guide) and your organization ID.
2. Install into your client:

{
  "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] Start with WIKI_READ_ONLY=true — the server won't even register write tools. Flip it to false once you trust your agent with edits.

3. Ask your agent something — see below.

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

What can it do

"Find our onboarding docs and summarize the key steps."

"What do we have on incident response? Open the most relevant page."

"Create a page team/weekly-notes and append today's standup summary."

"Add a row to the on-call rotation grid: alice, next week."

"Upload this PDF to the project page and link it at the bottom."

"Delete the draft page, but keep the recovery token in case I change my mind."

Tools

27 tools. All write tools disappear when WIKI_READ_ONLY=true.

Search & read (8)

Pages: write (8)

Grids: write (11)

How it compares

Facts verified against the alternatives' docs and published code, July–August 2026.

Also worth knowing:

• brekhov-ilya/yandex-wiki-mcp (npm) — pages read / write / move, grids read-only; interactive PKCE token flow with auto-refresh, no full-text search
• n-r-w/yandex-mcp (Go) — Yandex Tracker + Wiki in one server, read-only by design (5 wiki read tools), no search; auth via IAM tokens from the yc CLI only — Yandex OAuth tokens are not supported

As of July 2026, full-text search exists only here (up to 50 results) and in slartus (up to 10); the combination of search, grid 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 undocumented-but-public POST /v1/search endpoint — the same backend that powers the Wiki web search bar. Search first, then open a result with page_get by its slug.

• Up to 50 results per call (limit is clamped to 1–50; the API rejects anything else).
• Search is global only — slug_prefix and result_type filters are applied client-side after fetching, so combine them with limit=50 to avoid missing matches.
• 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, nothing is highlighted, 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. Read the page with page_get before answering from it. Empty for file results.

Traversing the tree

page_get_descendants 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. Prefer 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

Deployment

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 via Docker (the MCP endpoint is 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] The server writes no log files of its own — everything goes to stderr, which Docker's default json-file driver stores without a size limit. The --log-opt flags above cap it; drop them only if your daemon already sets a default.

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"

Security

• Read-only is server-side: with WIKI_READ_ONLY=true write tools are never registered — there is nothing for a confused agent to call.
• Wiki API does not enforce OAuth scopes (verified live — see docs/api-notes.md): a wiki:read token can write, so use the read-only mode rather than relying on token scopes.
• Secrets are SecretStr throughout — masked in logs and repr; DEBUG HTTP logging never includes headers or bodies.
• Deletion is recoverable: page_delete returns a recovery token for page_recover.
• Unrelated keys in a shared .env are ignored, but a misspelled setting (WIKI_READ_ONL) stops the server instead of silently falling back to a default you did not choose.

Development

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

Before committing, run the full verification set from CONTRIBUTING.md. Verified API behavior and probe scripts are documented in docs/api-notes.md.

The Wiki API drifts (its undocumented search endpoint silently changed contract once already) — scripts/contract_sweep.py re-verifies every client method against a live organization and reports validation mismatches and undeclared keys:

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

The API drift check workflow runs the same sweep weekly when the DRIFT_* repository secrets are configured (instructions in the workflow header); without them it skips quietly.

Credits

This project began as a fork of APonkratov/yandex-wiki-mcp (ya-yandex-wiki-mcp) by Aleksandr Ponkratov, an excellent, well-tested Python MCP server for the Yandex Wiki API, licensed under Apache-2.0. It has since grown its own surface — full-text search, typed input and output schemas across all 27 tools, YFM helpers, cursor draining, multi-user OAuth and a live contract sweep against the API — while the original copyright and license are preserved (see LICENSE and NOTICE).

The idea and key API findings behind full-text search come from slartus/mcp-yandex-wiki (JavaScript, MIT): it was the first to discover the undocumented POST /v1/search endpoint and to report that OAuth scopes are not enforced. No code was taken from it — only findings and ideas, independently re-verified against a live organization and extended here.

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