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

快速安装 ​

官方提供内置安装命令,可自动写入客户端配置并与已有 MCP 配置合并:

bash
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor

支持的客户端包括 claude-desktop、vscode、cursor、windsurf、cline、trae。也可以使用交互式安装:

bash
npx yuque-mcp setup

手动配置 ​

通用 stdio 配置:

json
{
  "mcpServers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "yuque-mcp"],
      "env": {
        "YUQUE_PERSONAL_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Claude Code 也可以直接添加:

bash
claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN

如果使用私有化语雀实例,通过 YUQUE_BASE_URL 或 --base-url 指定 API 地址:

bash
npx yuque-mcp --token=YOUR_TOKEN --base-url=https://yuque.example.com/api/v2

不指定时默认使用:

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_PERSONAL_TOKEN is required设置 YUQUE_PERSONAL_TOKEN,或在命令中传入 --token=YOUR_TOKEN
401 UnauthorizedToken 无效、过期或权限不足,到语雀开发者设置重新生成
429 Rate Limited请求过于频繁,降低批量读取频率后重试
客户端找不到工具更新为 npx -y yuque-mcp@latest,并重启 MCP 客户端
找不到 npx安装 Node.js 18 或更高版本,并确认终端 PATH 生效

注意事项 ​

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

相关页面 ​