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.

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.

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 \
  ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest

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

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