yandex-wiki-search-mcp

English | Русский

Yandex Wiki Search MCP

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

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

• 🔍 全文搜索整个 Wiki——使用与 Wiki 网页搜索栏相同的后端，每次查询最多返回 50 条结果
• 📄 完整的页面生命周期——创建、更新、追加（顶部 / 底部 / 锚点）、克隆、删除（附恢复令牌）、评论、文件上传
• 📊 动态表格（网格）——11 个写入工具：行、列、单元格、复制、排序
• 🔒 服务端只读模式——WIKI_READ_ONLY=true 会直接取消注册写入工具，因此 Agent 无法绕过该限制
• 🧩 类型化工具接口——每个工具都提供输入 JSON 模式和安全注解（只读 / 破坏性 / 幂等提示）；除 page_read_attachment 外，每个工具也都提供输出模式。该工具会返回原生图像或资源块
• 🐳 可在任何环境运行——桌面客户端使用 stdio，团队使用 streamable-http + Docker（可选多用户 OAuth）

快速开始

1. 获取具有 Wiki 访问权限的 Yandex OAuth 令牌（官方指南）和组织 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"}
    }
  }
}

提示

建议从 WIKI_READ_ONLY=true 开始——服务甚至不会注册写入工具。 确认可以信任你的 Agent 进行编辑后，再将其改为 false。

3. 向你的 Agent 提问——见下文。

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

能做什么

“帮我们找出入职文档，并总结关键步骤。”

“我们有哪些关于事件响应的资料？打开最相关的页面。”

“创建页面 team/weekly-notes，并附上今天的站会摘要。”

“在值班轮班表中添加一行：alice，下周。”

“将这份 PDF 上传到项目页面，并在底部添加链接。”

“删除草稿页面，但保留恢复令牌，以防我改变主意。”

工具

共有 33 个工具。设置 WIKI_READ_ONLY=true 后，所有写入工具都会消失。

搜索与读取（10）

页面：写入（12）

表格：写入（11）

根据 2026 年 7 月至 8 月查阅的替代方案文档和已发布代码核实的信息； 官方托管服务的工具列表于 2026-08-11 从 mcp.wiki.yandex.net 实时获取 （wiki-mcp-server 1.28.1）。

另有一些值得了解的方案：

• best-doctor/mcp-yandex-wiki（Python）— 创建 / 更新页面并读取页面；另有独立的 -ro 只读入口；不支持删除 / 恢复、表格或搜索；仅提供 PyPI
• brekhov-ilya/yandex-wiki-mcp（npm）— 页面读 / 写 / 移动，表格只读；支持交互式 PKCE 令牌流程并自动刷新，不支持全文搜索
• n-r-w/yandex-mcp（Go）— 在同一服务中整合 Yandex Tracker + Wiki，按设计为只读（5 个 Wiki 读取工具），不支持搜索；仅通过 yc 命令行获取 IAM 令牌进行身份验证 — 不支持 Yandex OAuth 令牌
• bim-ba/ycli（Python）— 一套整合 Tracker + Wiki + Forms 的工具包：包含 CLI、Python SDK、Claude Code 插件，以及 Wiki 功能涵盖 42 个 wiki_* 工具的 MCP 服务（15 个读取 / 27 个写入，带注释，并提供 --read-only 标志）；无全文搜索工具，附件下载仅支持 CLI/SDK

截至 2026 年 8 月，只有本项目（最多 50 条结果）和 slartus（最多 10 条）支持全文搜索 — Yandex 自己的托管服务并未提供搜索工具 — 而搜索、表格写入、服务端只读模式和类型化架构的组合，是本项目独有的。

本项目是 ya-yandex-wiki-mcp 的分支，并以 slartus/mcp-yandex-wiki 的研究成果为基础 — 请参阅致谢。

全文搜索

page_search 封装了 POST /v1/search 端点——与 Wiki 网页搜索栏使用同一后端。该 API 一直未公开，直到 Yandex 于 2026 年 8 月发布了 API 参考。先搜索，再通过结果的 slug 用 page_get 打开页面。

• 两种传输模式。默认模式：单次调用最多返回 50 条结果（limit 会被限制在 1–50 之间；API 不接受其他值），且不支持分页——响应中的游标始终为 null。设置 highlight=true 时：每页最多返回 10 条结果，不受 limit 影响；匹配内容会用 <em> 包裹，cursor（在 next_cursor 中原样返回的页码）最多可遍历约 100 条结果。如果 results 为空，或非空页面的 next_cursor 为 null，则表示结果集结束——到达末尾后，next_cursor 会在空页面上继续递增，因此它本身并不表示“还有更多结果”。
• 筛选条件在服务端、应用 limit 之前执行——筛选后的搜索不会因此漏掉匹配项：slug_prefix（分区筛选，支持 tech-doc/ml 等深层前缀）、result_type（page/file）、authors（通过 uid/cloud_uid 指定页面所有者——user_get_current 可提供你自己的标识，让“查找我关于 X 的页面”只需两次调用），以及 created_between/modified_between 日期范围（必须提供起止边界——API 不接受开放范围）。
• 支持带引号的 "exact phrase" 查询；page 结果会返回绝对的 https://wiki.yandex.ru/... 链接，file 结果会返回直接下载链接。
• content 是约 510 个字符的摘录，不是页面内容，也不是摘要：摘录取自匹配内容所在的位置，其中不一定包含查询词；其中的换行和制表符是页面自身的排版（表格单元格以制表符分隔），而不是片段之间的分隔符。传入 highlight=true 可用 <em> 标签包裹匹配内容。回答相关问题前，请先用 page_get 阅读页面。file 结果的 content 为空。

遍历树结构

page_get_descendants 会将任意嵌套层级的子树作为一份由 {id, slug} 组成的扁平列表返回。传入 from_root=true 而不是 page_id/slug，即可遍历整个 Wiki——当不知道起始 slug 时，可用这种方式进入，因此搜索并非唯一入口。知道分区 slug 时，优先使用它：Wiki 的页面数量可达数千，而 fetch_all 达到约 500 项的上限后会停止，并返回 truncated: true。

更多已验证的 API 行为（作用域、403 语义、错误封装、限制）：docs/api-notes.md。

配置

部署

%%{init: {"flowchart": {"wrappingWidth": 300}}}%%
flowchart LR
    L["Local MCP client<br/>Claude / Cursor /<br/>Windsurf / VS Code<br/>single user"]
    T["Team MCP clients<br/>multi-user,<br/>optional OAuth"]
    S["yandex-wiki-search-mcp"]
    W["Yandex Wiki API"]
    R[("Redis<br/>optional OAuth<br/>token store")]
    L -- "stdio" --> S
    T -- "streamable-http" --> S
    S --> W
    S -.-> R

通过 Docker 运行 HTTP 服务（MCP 端点为 http://localhost:8000/mcp）：

docker run --env-file .env -e TRANSPORT=streamable-http -p 127.0.0.1:8000:8000 \
  --log-opt max-size=10m --log-opt max-file=3 \
  ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest

警告

如果未设置 OAUTH_ENABLED=true，HTTP 端点本身不进行身份验证：任何能访问该端口的人都可以使用你的 WIKI_TOKEN。示例仅在回环地址上发布端口，因此其他机器无法访问；服务也只响应回环地址的 Host 名称，因此网页无法通过将自身名称重新绑定到 127.0.0.1 来访问服务（参见 MCP_ALLOWED_HOSTS）。 这两者都不属于身份验证：本机上的任何进程仍可使用该服务。只有在通过身份验证的反向代理后，或启用 OAuth 后，才应扩大访问范围。

说明

服务不会写入自己的日志文件——所有内容都会写入 stderr，而 Docker 默认的 json-file 驱动会将其存储起来，且不设大小限制。 上方的 --log-opt 标志会限制日志大小；仅当你的守护进程已设置默认限制时才可移除这些标志。

services:
  mcp-wiki:
    image: ghcr.io/dlbolshov/yandex-wiki-search-mcp:latest  # or: build: .
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      - WIKI_TOKEN=${WIKI_TOKEN}
      - WIKI_ORG_ID=${WIKI_ORG_ID}
      - TRANSPORT=streamable-http
      # Only if another container reaches it as http://mcp-wiki:8000:
      # - MCP_ALLOWED_HOSTS=localhost,127.0.0.1,mcp-wiki
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

• 只读在服务端强制执行：设置 WIKI_READ_ONLY=true 后，不会注册写入工具——困惑的 Agent 无从调用。
• 使用纯令牌的 HTTP 未经身份验证：使用 HTTP 传输且关闭 OAuth 时，任何能访问该端口的调用方都将以 WIKI_TOKEN 所有者的身份行事——该令牌能够访问的任何组织都不例外，因为端点上的 ?orgId=/?cloudOrgId= 会覆盖已配置的组织。请仅在环回地址上使用，或置于可进行身份验证的代理之后，或者启用 OAuth。仅使用环回地址无法阻止这样一种网页：它将自己的名称重新绑定到 127.0.0.1。因此，服务也只响应 MCP_ALLOWED_HOSTS 中列出的 Host 名称——默认仅限环回地址。本地文件系统工具（page_upload_attachment、page_download_attachment）仅通过 stdio 注册，因此 HTTP 服务绝不会代替调用方读写自己的磁盘。
• Wiki API 不会强制执行 OAuth 范围（Yandex 记录这些范围后，于 2026-08-11 再次验证——参见 docs/api-notes.md）：wiki:read 令牌仍然可以写入，因此请使用只读模式，不要依赖令牌范围。
• 密钥始终使用 SecretStr——在日志和 repr 中会被遮蔽；DEBUG HTTP 日志绝不包含标头或正文。
• 删除可恢复：page_delete 会返回一个用于 page_recover 的恢复令牌。
• 共享 .env 中无关的键会被忽略，但拼错的设置（WIKI_READ_ONL）会导致服务停止，而不是悄悄回退到你未选择的默认值。

开发

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

uv 会从 Python 3.11–3.14 中选择解释器，这是 uv.lock 包含 wheel 的版本范围 （.python-versions）；如果机器上没有合适的解释器，uv 会下载一个。

提交前，请运行 CONTRIBUTING.md 中列出的完整验证流程。 服务的架构——各层、代码索引、测试接缝、CI 和发布流程——见 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            # live contract checks
uv run python scripts/contract_sweep.py users/YOU/contract-sweep --cleanup  # remove fixtures

在 .env 中设置 SWEEP_SLUG=users/YOU/contract-sweep（参见 .env.example）后，可以省略 slug 参数；服务本身绝不会读取该变量。

配置好 DRIFT_* 仓库密钥后，API drift check 工作流会每周运行相同的扫描 （说明见工作流文件头）；未配置这些密钥时，工作流会静默跳过。

致谢

本项目最初是 APonkratov/yandex-wiki-mcp （ya-yandex-wiki-mcp）的分支，原项目由 Aleksandr Ponkratov 开发，是一个出色且经过充分测试的 Yandex Wiki API Python MCP 服务，采用 Apache-2.0 许可证。此后，本项目发展出了自己的功能——全文搜索、全部 33 个工具的类型化输入架构和 32 个工具的输出架构、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 无关联，也未获得其赞助或认可——使用这些名称仅用于说明该服务连接的是哪个服务。此 Logo 为原创标识，既不复刻 Yandex Wiki，也不复刻 MCP 品牌形象（设计说明）。

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