English | Русский

Yandex Wiki Search MCP

将 Claude、Cursor、Windsurf 或任何 MCP 客户端连接到 Yandex Wiki：全文搜索、页面、评论、附件和动态表格（“grids”）——共 33 个工具，全部带类型化 JSON 模式。

非官方项目：与 Yandex 无关，也未获 Yandex 认可。

• 🔍 全文搜索可覆盖整个 wiki——与 Wiki 网页搜索栏使用同一个后端，每次查询最多返回 50 条结果

• 📄 完整页面生命周期——创建、更新、追加（顶部 / 底部 / 锚点）、克隆、删除（可带恢复令牌）、评论、文件上传

• 📊 动态表格（grids）——11 个写入工具：行、列、单元格、复制、排序

• 🔒 服务端只读模式——WIKI_READ_ONLY=true 时服务端根本不会注册写入工具，因此代理无法绕过

• 类型化工具面——每个工具都附带输入 和 输出 JSON 模式，以及安全注解（只读 / 破坏性 / 幂等提示）

• 随处可运行——桌面客户端用 stdio；团队可用 streamable-http + Docker（可选多用户 OAuth）

快速开始

1. 获取具有 Wiki 访问权限的 Yandex OAuth 令牌（[官方指南](https://yandex.ru/support/wiki/ru/api-ref/access））和组织 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 1.x 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 上传到项目页面，并在底部加入链接。” “删除草稿页面，但保留一把恢复令牌，万一改变主意。

工具

共 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 年 7–8 月）；官方托管服务器自身的工具列表从 mcp.wiki.yandex.net 实时捕获（wiki-mcp-server 1.28.1，2026-08-11）。

另外一些值得介绍的库/项目：

• best-doctor/mcp-yandex-wiki（Python）— 页面创建 / 更新 + 读取，支持独立的 --` 只读入口点；无删除 / 恢复、无表格、无搜索；仅 PyPI 发行。

• brekhov-ilya/yandex-wiki-mcp（npm）— 页面读取 / 写入 / 移动，表格只读；交互式 PKCE token 流程，支持自动刷新，无全文搜索。

• n-r-w/yandex-mcp（Go）— 单个服务端内置 Yandex Tracker 和 Wiki，设计上为只读（5 个 wiki 读取工具），无搜索；只支持通过 yc CLI 的 IAM 令牌认证，Yandex OAuth 令牌不支持。

• bim-ba/ycli（Python）— 针对 Tracker + Wiki 的一网络工具： CLI、Python SDK、Claude Code 插件，以及一个 MCP 服务端，其中 Wiki 接口提供 42 个 wiki_* 工具（15 个读取 / 27 个写入，带注解，支持 --read-only 标记）；无全文搜索工具；附件下载仅存于 CLI/SDK。

截至 2026 年 8 月，全文搜索只存在于本项目（最多 50 条结果）和 slartus/mcp-yandex-wiki（最多 10 条结果）中；Yandex 自己的托管服务不带搜索工具了，而同时具备搜索、表格写入、服务端只读模式和类型化 schema 的功能组合是这个项目独有的。

本项目是 ya-yandex-wiki-mcp 的分支（fork），并基于 slartus/mcp-yandex-wiki 的研究成果，详见 致谢。

全文搜索

page_search 封装了 POST /v1/search 端点——这正是 Wiki 网页搜索栏的底层接口，在 Yandex 于 2026 年 8 月发布API 参考文档之前一直没有公开文档。先搜索，然后用 page_get 通过 slug 打开结果即可。

• 两种网络模式。默认情况下：一次调用最多返回 50 条结果（limit 被限制在 1–50；API 拒绝其他值），不提供分页——响应中的 cursor 始终为 null。使用 highlight=true 时，结果页硬上限为 10，且不受 limit 影响，匹配内容会放进 <em> 标签内，由 cursor（在 next_cursor 中回显的页号）最多可游历 ~100 条结果。当 results 返回空或非空页面的 next_cursor 为 null 时，结果集结束——不过在末尾之后 next_cursor 仍会继续增长，所以仅有 next_cursor 并不代表还有更多。

• 服务端过滤，先于 limit 生效——所以带过滤的搜索不会因此丢失匹配：slug_prefix（按分区块过滤，像 tech-doc/ml 这类深层前缀也有效）、result_type（page/file）、authors（按页面属主 uid/cloud_uid 过滤，还可以通过 user_get_current 获取自己的值，让“找提及我的页面”变为两次请求），以及 created_between/modified_between 日期区间（两个边界都需要填写，API 不接受开放式区间）。

• 支持带引号的 "exact phrase" 搜索；page 结果得到 https://wiki.yandex.ru/... 绝对链接，file 结果是直接下载链接。

• content 是一个 约 510 字节的摘要而非页面本身文章不是概括：原文是从匹配位置开始的截取，搜索词不一定出现在这段文本中；它的回行和标签是页面原有的版式（单元格数据用制表符分隔），而不是候选片段间分隔符。用 page_get 读取页面后才可从中作答。对于 file 结果，该字段为空。

遍历目录树

page_get_descendants 返回一颗子树作为一个扁平 {id, slug} 列表，包含每个层级。传入 from_root=true 而不是 page_id/slug 时，会 json 形式遍历 整个 Wiki——当不知道起始 slug 时只能用它，所以搜索不是唯一入口。有起始 slug 时优先用 slug 传入；Wiki 动辄数千页，fetch_all 约 500 条会截断，返回 truncated: true。

更多已验证的 API 行为（作用对象、403 语义错误、错误包装、限制）：更多服务端说明。

配置

当 OAUTH_ENABLED=true 时，服务器变为 OAuth 提供方：每个 MCP 用户用自己的 Yandex 账户授权，向 Wiki API 发出的请求使用其个人令牌。page_upload_attachment 和 page_download_attachment 在此模式下不会注册：它们会读取/写入运行服务器的机器里的文件，而在共享部署中，该机器并不是调用方的机器。

按用户选择组织。 在 OAuth 下，WIKI_ORG_ID / WIKI_CLOUD_ORG_ID 是可选的，因为每个请求都能指明自己的组织：在你的客户端连接的 MCP 服务器 URL 后面追加 ?orgId=...（或 ?cloudOrgId=...）。查询参数优先于全局设置，因此一个服务器可以服务多个组织。如果请求两者都没有携带，工具调用会失败，并返回一条指向这两个选项的提示——如果所有用户都共享同一个组织，就把它设为环境变量的默认值。

完整带注释的列表参见 .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

通过 Docker 运行 HTTP 服务器（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"

redis 存储 OAuth 的场景下，使用现有的 compose.yaml 作为基线。

安全

• 只读是服务端的：设置 WIKI_READ_ONLY=true 后，写工具根本不注册——一个被误导的 agent 也就无（工）可调。

• Wiki AP I 无法强制 OAuth 作用域（2026-08-11 经 Yandex 文档 sync 后重新验证，见 docs/api-notes.md）：一个 wiki:read 的令牌照样能写。因此请用只读模式，而不要依赖令牌 Scope。

• 凭据全程都是 SecretStr——日志与 repr 中会被遮蔽；DEBUG 级别 HTTP 日志永远不带标头或正文。

• 删除是可恢复的：page_delete 会返回一个给 page_recover 使用的恢复令牌。

• 共享 .env 里不相关的键会被忽略，但一个拼错的配置（WIKI_READ_ONL）会让 server 直接停掉，而不是默默落回你并未实际选择的默认值。

开发

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

提交前，先执行 CONTRIBUTING.md 里完整的验证集合。关于服务器是如何构建的——层结构、代码地图、测试接缝、CI 和 release 过程——参见 docs/architecture.md。你以为 []，但请确认：已验证的 API 行为和探针脚本记录在 docs/api-notes.md 中。

Wiki API 会出现漂移（搜索端点曾在没有文档时就已经静默改动过一次契约）——scripts/contract_sweep.py 会对照一个真实组织重新验证每个客户端方法，并报告校验不匹配和未声明的键：

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 漂移检查 工作流在配置了 DRIFT_* 仓库机密时会每周运行相同的扫描（说明见工作流头部）；未配置这些机密时则静默跳过。

致谢

本项目最初是从 Aleksandr Ponkratov 的 APonkratov/yandex-wiki-mcp（ya-yandex-wiki-mcp）复刻而来；该原项目是一个出色且经过充分测试的、面向 Yandex Wiki API 的 Python MCP 服务器，基于 Apache-2.0 许可。此后，本项目已发展出自身独立的功能体系：全文搜索、覆盖全部 33 个工具的类型化输入 和 输出 schema、YFM 辅助工具、游标耗尽、多用户 OAuth，以及针对 API 的实时契约扫描；同时保留了原版权和许可（见 LICENSE 和 NOTICE）。

全文搜索背后的思路和关键 API 发现来自 slartus/mcp-yandex-wiki（JavaScript，MIT）：该项目首先发现了当时尚属未记录的 POST /v1/search 端点（Yandex 直到 2026 年 8 月才发布其接口参考），并指出 OAuth 作用域并未被强制执行。我们没有借鉴它的代码，只是使用了它的发现和思路，并在真实组织上独立重新验证和扩展。

商标

“Yandex” 和“Yandex Wiki” 是 YANDEX LLC 的商标。这是一个非官方的社区项目，与 Yandex 无关联、未受到 Yandex 赞助或认可；这些名称仅为指称性地使用，用于说明服务器所对接的是哪项服务。该 Logo 是一个原创标识，既没有复刻 Yandex Wiki 的品牌，也没有复刻 MCP 的品牌（设计说明）。

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