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"}
    }
  }
}

3. Ask your agent something — see below.

The server runs on MCP Python SDK v2. That is invisible to clients — one v2 server answers every protocol revision back to 2024-11-05 as well as the current one, so there is nothing to change on your side and nothing to reinstall.

The only reason to hold back is a shared environment that pins mcp<2 for something else. 1.0.1 is the last release built on the 1.x SDK and stays on PyPI:

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

Related MCP server: mediawiki-mcp-server

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)

Grid specifics:

• Mutations use optimistic locking — fetch the grid first and pass the latest revision.

• grid_update.default_sort takes [{"column": "status", "direction": "asc"}] entries; the server converts them to the wire format the API expects.

• grid_add_columns requires required on every column because the real API validates it.

• grid_copy returns operation metadata, not a ready copied grid object.

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

With OAUTH_ENABLED=true the server becomes an OAuth provider: each MCP user authorizes with their own Yandex account, and requests to the Wiki API are made with their personal token. page_upload_attachment is not registered in this mode: it reads files from the machine the server runs on, which is not the caller's machine in a shared deployment.

Choosing the organization per user. WIKI_ORG_ID / WIKI_CLOUD_ORG_ID are optional under OAuth, because each request can name its own organization: append ?orgId=... (or ?cloudOrgId=...) to the MCP server URL your client connects to. A query parameter wins over the server-wide setting, so one deployment can serve several organizations. If a request carries neither, the tool call fails with a message pointing at both options — set the environment variable as the default if all your users share one organization.

See .env.example for the full annotated list and compose.yaml for a Redis baseline.

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

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"

For Redis-backed OAuth storage, use the existing compose.yaml as the baseline.

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. How the server is put together — the layers, the code map, testing seams, CI and the release process — is described in docs/architecture.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