Purpose
yandex-wiki-search-mcp is an unofficial open-source project (not affiliated with or endorsed by Yandex) that serves as an MCP server connecting Yandex Wiki to Claude, Cursor, Windsurf, or any MCP client, enabling AI agents to search, read, and edit Wiki content. The project is released under the Apache-2.0 license (retaining the license and copyright notices from the fork source), and the README is available in English and Russian.
Main capabilities
- Full-text search: wraps the POST /v1/search endpoint, using the same backend as the Wiki web search bar, returning up to 50 results per query by default. When highlight=true is used, results are hard-capped at 10, matching content is wrapped in <em> tags, and pagination can continue via cursor, up to about 100. Quoted exact-phrase queries are supported; page results return https://wiki.yandex.ru/... absolute links, and file results return direct download links.
- Filters (executed server-side before limit): slug_prefix (can go deep into prefixes such as tech-doc/ml), result_type (page / file), authors (specify page owners by uid / cloud_uid; use user_get_current to get your own), and created_between / modified_between date ranges (both ends must be provided).
- Full page lifecycle: create, update, append (top / bottom / anchor), clone, delete with restore token, comments, file upload.
- Dynamic tables (grids): 11 write tools for manipulating rows, columns, and cells, with copy and sort support. Among them, grid_update.default_sort accepts entries in the form [{"column": "status", "direction": "asc"}] and the server converts them; grid_add_columns requires required for each column; grid_copy returns operation metadata rather than the copied table object; changes use optimistic locking, requiring fetching the table first and passing the latest revision.
- Traversal: page_get_descendants returns a flat {id, slug} list for a subtree; from_root=true can traverse the entire Wiki (fetch_all truncates at about 500 items and marks truncated: true).
- All 33 tools have input JSON schemas and safety annotations (read-only / destructive / idempotent hints), and all except page_read_attachment (which returns native image or resource blocks) have output schemas. The tools are divided into search and read (10), page write (12), and table write (11).
Usage
A Yandex OAuth token with Wiki access (official guide) and an organization ID are required.
Install to a client: the Claude Desktop badge can download the .mcpb package from the latest release; after double-clicking, Claude Desktop installs it automatically and prompts for the token and org ID (uv must already be installed).
It is recommended to start with WIKI_READ_ONLY=true first—in this case the server does not register write tools at all; after confirming trust, change it to false.
Example prompts: find the getting-started documentation and summarize the key steps; search for incident response-related content and open the most relevant page; create the page team/weekly-notes and append today's standup summary; add a row alice, next week to the on-call rotation table; upload a PDF to the project page and link it at the bottom of the page; delete a draft page but keep the restore token.
HTTP deployment (MCP endpoint is http://localhost:8000/mcp）：通过 Just run Docker. In OAuth mode (OAUTH_ENABLED=true), the server becomes an OAuth provider, each MCP user authorizes with their own Yandex account, and requests use their personal token; in this case page_upload_attachment and page_download_attachment are not registered (these two tools read and write files on the machine where the server runs, which under HTTP transport is not the caller's machine, so they are registered only via stdio).
Organized by user choice: under OAuth, WIKI_ORG_ID / WIKI_CLOUD_ORG_ID are optional, and ?orgId=... or ?cloudOrgId=... can be appended to the MCP URL the client connects to; query parameters take precedence over the server's global settings, making it easy to serve multiple organizations from one deployment; if neither is provided, tool calls fail and prompt with both paths.
For the full environment variables, see .env.example; for the Redis baseline, see compose.yaml.
Applicable scenarios and limitations
- Applicable: scenarios where a team accumulates documentation in Yandex Wiki and wants an AI agent to retrieve and maintain pages, tables, and attachments; deployments that need read-only safety constraints or independent multi-user authorization.
- Read-only is implemented server-side: when WIKI_READ_ONLY=true, write tools are not registered, so the agent has no way to call them.
- Security reminder: when using HTTP transport without OAuth enabled, anyone who can reach the port will operate as the owner of WIKI_TOKEN (?orgId= / ?cloudOrgId= can override the configured organization); you should listen only on the loopback address or place it behind an authenticating reverse proxy. The server only responds to Host names in MCP_ALLOWED_HOSTS (loopback by default), to prevent a web page from rebinding its own domain to 127.0.0.1.
- The Wiki API does not enforce OAuth scope (reviewed 2026-08-11); a wiki:read token can still write, so you should use read-only mode rather than relying on token scope.
- Deletion is recoverable: page_delete returns a recovery token for use by page_recover.
- Other: the server itself does not write log files; all output goes to stderr; DEBUG HTTP logs do not include request headers or bodies; a misspelled setting name in .env (such as WIKI_READ_ONL) directly prevents the server from starting, rather than silently falling back.
Version and runtime environment
Based on MCP Python SDK v2, a v2 server can answer all protocol versions since 2024-11-05, and clients need no changes or reinstallation; the only case where you need to stay on an older version is when other components in a shared environment pin mcp<2—1.0.1 is the last version based on the 1.x SDK and remains on PyPI. uv will choose an interpreter from Python 3.11–3.14, and automatically download one if none is available locally.
Compared with similar alternatives, as of August 2026 full-text search exists only in this project (up to 50 results) and slartus (up to 10 results); Yandex's official hosted server does not include a search tool. The combination of search, table writing, server-side read-only mode, and typed schemas is unique to this project.
Maintenance and provenance
The project was originally forked from Aleksandr Ponkratov's APonkratov/yandex-wiki-mcp (ya-yandex-wiki-mcp), and continues its Apache-2.0 license and copyright (see LICENSE, NOTICE); afterward it independently extended full-text search, input schemas for all 33 tools and output schemas for 32, YFM helpers, cursor handling, multi-user OAuth, and live contract scanning against the API. The idea for full-text search and the key API discoveries came from slartus/mcp-yandex-wiki (JavaScript, MIT); its code was not used, and the discoveries were only independently verified and extended.
The Wiki API drifts (the search endpoint once silently changed its contract during an undocumented period); scripts/contract_sweep.py can re-verify every client method against the actual organization and report validation mismatches and undeclared keys; after configuring the DRIFT_* repository secrets, the drift check workflow runs weekly. For architecture notes, see docs/architecture.md; for verified API behavior and probe scripts, see docs/api-notes.md.
The names "Yandex" and "Yandex Wiki" are trademarks of YANDEX LLC, and are used here only forSpecify the service to which the server is connected.