yuque-local-mcp

本地语雀 MCP server，通过你自己的浏览器登录态访问语雀，不使用语雀 OpenAPI token。

特性

• 只访问 config.json 里显式允许的知识库。
• 读取、新建、编辑文档都会先做 URL 白名单校验。
• 打开页面后再读取语雀页面里的 window.appData 做二次校验。
• 搜索只搜本地缓存，不做语雀全站搜索。
• 支持只读模式，适合先接入 AI 客户端观察行为。
• 写操作默认只把内容填进浏览器，要求人眼确认后再保存。

安装

从源码安装

git clone https://github.com/fanb129/yuque-local-mcp.git
cd yuque-local-mcp
npm install
npx playwright install chromium
npm run build
cp config.example.json config.json

npm / npx 使用

发布到 npm 后，MCP 客户端可以直接用：

npx -y yuque-local-mcp

首次登录和配置检查可以用：

npm exec --yes --package=yuque-local-mcp -- yuque-local-mcp-login
npm exec --yes --package=yuque-local-mcp -- yuque-local-mcp-doctor

如果你从源码运行，对应命令是：

npm run build
npm run login
npm run doctor

配置知识库白名单

复制并编辑 config.json：

{
  "browser": {
    "headless": false,
    "profileDir": "~/.yuque-local-mcp/profile",
    "defaultTimeoutMs": 30000,
    "slowMoMs": 0
  },
  "cacheDir": "~/.yuque-local-mcp/cache",
  "writeSafety": {
    "readOnly": false,
    "snapshotBeforeWrite": true,
    "requireHumanReviewInBrowser": true
  },
  "allowedBooks": [
    {
      "name": "我的知识库",
      "origin": "https://www.yuque.com",
      "group": "your-space",
      "book": "your-book"
    }
  ]
}

知识库 URL 如果是：

https://www.yuque.com/acme/frontend

那就是：

{
  "origin": "https://www.yuque.com",
  "group": "acme",
  "book": "frontend"
}

name 只是本地显示名，不需要和语雀页面上的知识库名称完全一致。如果知道 bookId，建议填上，MCP 会在页面加载后同时校验 bookId。

首次登录

先打开一个持久化 Chromium profile：

npm run login

或在 MCP 客户端里调用：

yuque_open_login

手动登录语雀后，后续工具会复用这个登录态。登录状态默认保存在 ~/.yuque-local-mcp/profile。

Codex 配置

本地源码方式：

[mcp_servers.yuque]
command = "node"
args = ["/absolute/path/to/yuque-local-mcp/dist/index.js"]
startup_timeout_sec = 20
tool_timeout_sec = 180
default_tools_approval_mode = "prompt"

[mcp_servers.yuque.env]
YUQUE_MCP_CONFIG = "/absolute/path/to/yuque-local-mcp/config.json"

[mcp_servers.yuque.tools.yuque_allowed_books]
approval_mode = "never"

[mcp_servers.yuque.tools.yuque_open_login]
approval_mode = "prompt"

[mcp_servers.yuque.tools.yuque_read_doc]
approval_mode = "never"

[mcp_servers.yuque.tools.yuque_get_toc]
approval_mode = "never"

[mcp_servers.yuque.tools.yuque_sync_book]
approval_mode = "prompt"

[mcp_servers.yuque.tools.yuque_search_cache]
approval_mode = "never"

[mcp_servers.yuque.tools.yuque_create_doc]
approval_mode = "prompt"

[mcp_servers.yuque.tools.yuque_update_doc]
approval_mode = "prompt"

如果已经发布到 npm，也可以把 command/args 改成：

command = "npx"
args = ["-y", "yuque-local-mcp"]

把这段合并到：

~/.codex/config.toml

“合并”不是覆盖整个文件，而是把这段追加或整理进你现有的 Codex 配置。

Claude Code 一键安装

本地源码方式：

claude mcp add -s user yuque \
  -e YUQUE_MCP_CONFIG=/absolute/path/to/yuque-local-mcp/config.json \
  -- node /absolute/path/to/yuque-local-mcp/dist/index.js

npm 发布后可直接使用：

claude mcp add -s user yuque \
  -e YUQUE_MCP_CONFIG=/absolute/path/to/config.json \
  -- npx -y yuque-local-mcp

检查安装结果：

claude mcp list
claude mcp get yuque

工具

• yuque_allowed_books：列出允许访问的知识库。
• yuque_open_login：打开浏览器登录语雀。
• yuque_read_doc：读取允许知识库内的文档并缓存。
• yuque_get_toc：读取允许知识库目录。
• yuque_sync_book：按目录同步最多 50 篇到本地缓存。
• yuque_search_cache：只搜索本地缓存。
• yuque_create_doc：在允许知识库中新建文档。
• yuque_update_doc：替换或追加允许知识库内文档内容。

只读模式

如果你希望 AI 客户端只能读语雀，不能新建或编辑文档：

{
  "writeSafety": {
    "readOnly": true,
    "snapshotBeforeWrite": true,
    "requireHumanReviewInBrowser": true
  }
}

开启后，yuque_create_doc 和 yuque_update_doc 在 dryRun=false 时会直接拒绝执行。读文档、读目录、同步缓存和搜索缓存不受影响。

写入确认模式

默认配置：

{
  "writeSafety": {
    "readOnly": false,
    "snapshotBeforeWrite": true,
    "requireHumanReviewInBrowser": true
  }
}

这表示：

• 编辑前会读取并保存原文快照。
• 新建/编辑会把 Markdown 作为剪贴板粘贴到浏览器，并在语雀提示时自动点击“立即转换”。
• 默认不会自动点击保存。
• 你确认无误后，在语雀浏览器窗口里手动保存。

如果你确认要自动尝试保存，可以改成：

{
  "writeSafety": {
    "readOnly": false,
    "snapshotBeforeWrite": true,
    "requireHumanReviewInBrowser": false
  }
}

不建议第一次接入就关闭人工确认。

发布到 npm

发布前检查：

npm run typecheck
npm run build
npm pack --dry-run

发布：

npm login
npm publish --access public

发布后，用户即可通过 npx -y yuque-local-mcp 在 Codex、Claude Code 或其他 MCP 客户端中启动服务。

常见问题

登录过期怎么办？

重新运行 npm run login，或在 MCP 客户端里调用 yuque_open_login，在打开的浏览器里重新登录语雀。登录完成后再次调用读取或写入工具。

读取时遇到 401 怎么办？

一般是登录态失效、当前账号没有目标知识库权限，或白名单配置和 URL 不匹配。先确认浏览器里能手动打开该文档，再检查 allowedBooks 的 origin、group、book，如果配置了 bookId 也要确认它属于同一个知识库。

语雀 UI 改版导致写入失败怎么办？

这是浏览器自动化方案，不是语雀官方 API。语雀改版后，读操作通常更稳定，写操作可能需要更新选择器或交互步骤。建议保留 requireHumanReviewInBrowser=true，并在 issue 里提供失败页面、工具输入和错误日志。

遇到验证码怎么办？

验证码必须由你在浏览器里手动完成。本项目不会绕过验证码，也不会自动处理风控校验。完成验证后，保持该浏览器 profile 不变，再重试 MCP 工具。

重要限制

这是浏览器自动化方案，不是语雀官方 API。语雀 UI 改版、登录过期、验证码、编辑器粘贴行为变化都可能影响写入成功率。

第一版没有开放删除、权限修改、分享公开、批量移动等危险操作。

License

MIT