ACORG docs

主题

语雀 MCP ​

语雀 MCP 适合把语雀个人知识库、团队知识库、项目文档和小记接入 AI 客户端,用于知识检索、需求理解、文档生成和知识库维护。

官方生态文档:https://yuque.github.io/yuque-ecosystem/

核心 MCP Server:https://github.com/yuque/yuque-mcp-server

适用场景 ​

  • 搜索语雀知识库中的产品说明、研发规范、接口文档、会议纪要和历史方案。
  • 读取指定知识库、文档目录或页面正文,让 Agent 总结业务规则、领域术语和已有决策。
  • 根据需求文档生成实现计划、验收清单、风险点和待确认问题。
  • 在授权范围内创建或更新知识库文档、小记、目录和资源。
  • 结合语雀生态插件中的 Skills 做读书摘要、智能搜索、知识串联、周报和团队知识报告。

安装与配置 ​

语雀 MCP Server 是本地 stdio 服务,通过 npx 启动。当前官方 README 推荐 Node.js 18 或更高版本。

先到语雀开发者设置创建 Token，优先只授予目标知识库所需权限:

text
https://www.yuque.com/settings/tokens

交互式安装（推荐） ​

官方提供交互式安装入口，按提示选择客户端、输入 Token；避免将真实 Token 拼进命令行或手动编辑配置文件:

bash
npx yuque-mcp setup

官方内置安装器支持 claude-desktop、vscode、cursor、windsurf、cline、trae、qoder、opencode。ChatGPT 桌面端并不在该安装器的列表内：若要在该客户端使用，从 Settings > MCP servers > Add server 添加 STDIO 服务，仅在客户端支持安全保存环境变量时填写 YUQUE_TOKEN；启动命令为 npx，参数为 -y yuque-mcp。不要把 Token 粘贴进命令参数或项目文件。具体客户端能力以官方通用客户端说明为准。

团队空间绑定 Token 或私有部署需要设置 YUQUE_HOST（站点或空间的 HTTPS 地址，例如 https://your-space.yuque.com）。YUQUE_PERSONAL_TOKEN、YUQUE_BASE_URL 和 --base-url 仅用于兼容旧配置，新配置优先使用 YUQUE_TOKEN、YUQUE_HOST。不设置 Host 时默认使用:

text
https://www.yuque.com/api/v2

工具能力 ​

官方核心 server 当前提供 19 个工具,覆盖用户、搜索、知识库、文档、资源、目录和小记:

分类典型工具用途
用户yuque_get_user获取当前授权用户信息
搜索yuque_search搜索文档或知识库
知识库yuque_list_books、yuque_get_book、yuque_create_book、yuque_update_book查询、创建和更新知识库
文档yuque_list_docs、yuque_get_doc、yuque_create_doc、yuque_update_doc列出、读取、创建和更新文档
资源yuque_get_resource、yuque_create_resource、yuque_update_resource管理资源内容
目录yuque_get_toc、yuque_update_toc读取和更新知识库目录
小记yuque_list_notes、yuque_get_note、yuque_create_note、yuque_update_note查询、创建和更新小记

实际可用工具以客户端中的 tools/list 返回为准。写入类工具会改变语雀内容,建议在提示词中要求 Agent 先列出目标文档和修改计划。

典型工作流 ​

搜索并读取文档 ​

  1. 使用 yuque_search 按关键词搜索知识库或文档。
  2. 从搜索结果中确认知识库 ID、文档 ID 或路径。
  3. 使用 yuque_get_doc 读取完整内容。
  4. 让 Agent 输出摘要、约束、待办项或待确认问题。

创建或更新项目文档 ​

  1. 使用 yuque_list_books 或 yuque_get_book 确认目标知识库。
  2. 使用 yuque_get_toc 确认目录结构。
  3. 创建文档时使用 yuque_create_doc;更新已有文档时先读取原文,再使用 yuque_update_doc。
  4. 如需调整目录,再调用 yuque_update_toc。

团队知识库接入 ​

  1. 为团队知识库准备最小权限 Token。
  2. 先只开放读取能力,验证搜索、读取和目录访问范围。
  3. 对写入、目录调整和资源更新设置人工确认步骤。
  4. 在提示词中明确知识库名称、文档路径、输出格式和禁止修改的范围。

提示词示例 ​

text
请在语雀中搜索这个需求相关的产品说明、研发规范和历史方案。
读取命中的文档后,整理业务背景、核心约束、接口影响、验收标准和待确认问题。
只读取信息,不要创建、更新或移动任何文档。
text
请读取语雀中这个项目知识库的目录结构和指定需求文档。
先列出你计划读取的文档清单,等我确认后再继续。

常见问题 ​

现象处理方式
YUQUE_TOKEN is required检查安装向导或客户端的安全凭据设置是否提供 YUQUE_TOKEN；不要把真实值放进命令历史
401 UnauthorizedToken 无效、过期或权限不足,到语雀开发者设置重新生成
429 Rate Limited请求过于频繁,降低批量读取频率后重试
客户端找不到工具更新为 npx -y yuque-mcp@latest,并重启 MCP 客户端
找不到 npx安装 Node.js 18 或更高版本,并确认终端 PATH 生效

注意事项 ​

  • Token 属于敏感凭据,不要写入公开仓库、共享文档或可被前端打包的文件。
  • 优先使用只读或最小权限验证知识库、文档和团队空间的访问范围。
  • 语雀知识库可能包含客户信息、内部规范、接口密钥或未公开方案,接入前要确认权限边界。
  • 知识库内容可能滞后于代码和线上行为,关键结论需要结合项目、Issue、PR 或正式审批记录验证。
  • 跨知识库引用、历史版本、评论信息和目录调整要在提示词中明确是否允许读取或修改。
  • 写入、评论、移动、删除或批量整理文档前,要求 Agent 先列计划并等待确认。

相关页面 ​