@joren.li/yuque-mcp

v0.1.2

Published

a month ago

MCP server for Yuque (语雀) — read & write docs over stdio, supports Token or Cookie auth

0High
0Medium
0Low

joren.li

mcp model-context-protocol yuque 语雀 cursor claude stdio

@joren.li/yuque-mcp

一个用于访问语雀（默认指向 https://bd-tech.yuque.com/）的 MCP Server，基于 Model Context Protocol SDK 构建，使用 stdio 传输，可直接接入 Cursor、Claude Desktop 等支持 MCP 的客户端。

快速开始

无需 clone 仓库，通过 npx 直接拉起即可：

YUQUE_COOKIE='把整段 cookie 粘到这里' npx -y @joren.li/yuque-mcp

正常情况下进程会前台运行并等待 stdio 输入。在客户端（Cursor / Claude Desktop）里通过 MCP 配置拉起即可，详见下文的接入 Cursor 一节。

系统要求：Node.js >= 18

鉴权方式

本 MCP 支持两种鉴权方式，任选其一。如果同时配置了两者，Token 优先生效。

方式 A：Cookie（推荐）

适合公司禁用了 Personal Token、或不方便申请 Token 的场景。直接复用浏览器里的登录态，不需要任何 Token。

操作步骤：

浏览器登录 https://bd-tech.yuque.com/
按 F12 打开开发者工具，切换到 Network 面板
刷新页面，点击列表中任意一个请求，右侧 Headers → Request Headers
找到 cookie: 这一行，整行的值全部复制（形如 _yuque_session=xxx; yuque_ctoken=yyy; ...）
将复制内容粘贴到环境变量 YUQUE_COOKIE

注意事项：

Cookie 通常几天到几周会过期，失效后会收到 401，重新拷一次即可。
写操作（创建 / 更新 / 删除）会自动从 Cookie 中提取 yuque_ctoken 字段作为 CSRF Token。如果 Cookie 中缺失该字段（极少见），写操作会失败，请重新拷取完整的 cookie 行。
Cookie 等同于你的登录密码，请只在本地使用，不要提交到 git，不要分享给他人。

方式 B：Personal Token

适合允许使用 Token 的场景，权限粒度更细，相对安全。

操作步骤：

浏览器登录 https://bd-tech.yuque.com/
打开 https://bd-tech.yuque.com/settings/tokens
点击新建 Token，按需勾选权限：
- 只读使用：勾选 读取 (Read) 即可
- 需要写入文档：再勾选 写入 (Write)
复制生成的 Token，配置到环境变量 YUQUE_TOKEN

接入 Cursor

打开 Cursor → Settings → MCP，或直接编辑 ~/.cursor/mcp.json，加入如下配置：

Cookie 模式（推荐）

{
  "mcpServers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "@joren.li/yuque-mcp"],
      "env": {
        "YUQUE_COOKIE": "_yuque_session=xxx; yuque_ctoken=yyy; acw_tc=zzz; ..."
      }
    }
  }
}

Token 模式

{
  "mcpServers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "@joren.li/yuque-mcp"],
      "env": {
        "YUQUE_TOKEN": "your_personal_token"
      }
    }
  }
}

保存后，在 Cursor MCP 设置里点 Restart 重启该 server，或重启 Cursor。

接入 Claude Desktop

编辑配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

加入：

{
  "mcpServers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "@joren.li/yuque-mcp"],
      "env": {
        "YUQUE_COOKIE": "_yuque_session=xxx; yuque_ctoken=yyy; ..."
      }
    }
  }
}

保存后重启 Claude Desktop。

环境变量参考

| 变量 | 默认值 | 说明 | | --- | --- | --- | | YUQUE_COOKIE | — | 浏览器拷出的整行 Cookie，与 YUQUE_TOKEN 二选一 | | YUQUE_TOKEN | — | 语雀 Personal Token，与 YUQUE_COOKIE 二选一，优先生效 | | YUQUE_BASE_URL | https://bd-tech.yuque.com/api/v2 | API 基础地址，需要切到其他语雀空间时改这里 | | YUQUE_USER_AGENT | yuque-mcp/<version> | 自定义 User-Agent（语雀官方要求请求带 UA） |

提供的工具

| 工具 | 说明 | | --- | --- | | yuque_get_current_user | 获取当前鉴权对应的用户信息（健康检查首选） | | yuque_get_user | 通过 login / id 获取指定用户 | | yuque_list_user_groups | 列出当前用户或指定用户加入的团队 | | yuque_get_group | 获取团队详情 | | yuque_list_repos | 列出某 user 或 group 下的所有知识库 | | yuque_get_repo | 获取知识库详情（支持完整 URL） | | yuque_get_repo_toc | 获取知识库目录树 | | yuque_list_docs | 列出知识库下的文档（仅元数据，不含正文） | | yuque_get_doc | 读取文档正文：传 URL 或 namespace + slug，默认返回 Markdown | | yuque_search | 全站搜索：doc / repo / group / user | | yuque_create_doc | 新建文档（Markdown） | | yuque_update_doc | 更新文档（按 URL 或 namespace + id 定位） | | yuque_delete_doc | 删除文档 | | yuque_request | 兜底：直接调用任意语雀 API 路径 |

常见用法

直接给链接，让模型自动读取

帮我读一下 https://bd-tech.yuque.com/xxx/yyy/zzz 然后总结一下要点

模型会自动调用 yuque_get_doc 获取正文。

列表 → 定位 → 读取

1. 用 yuque_list_repos 列出 bd-tech 团队的所有知识库
2. 找到名字里含 "前端规范" 的那个
3. 用 yuque_get_repo_toc 看目录
4. 用 yuque_get_doc 读其中的某篇

写入文档

帮我在 xxx 知识库下新建一篇文档，标题为 yyy，内容为 ...

模型会调用 yuque_create_doc。前提：Cookie 模式下你的浏览器账号有该知识库的写权限；Token 模式下 Token 需勾选 Write 权限。

常见问题排查

第一步永远是先调用 yuque_get_current_user 自检鉴权状态。

| 现象 | 可能原因 | 解决 | | --- | --- | --- | | 401 Unauthorized | Cookie 过期 / Token 失效 | 重新拷 Cookie 或重建 Token | | 403 Forbidden（读取） | 当前账号没有该内容的访问权限 | 检查浏览器登录态是否能直接打开该页 | | 403 Forbidden（写入） | Token 缺少 Write 权限 | 重新生成 Token 时勾选 Write | | 写入操作偶发 403 / CSRF | Cookie 中缺少 yuque_ctoken | 重新从浏览器拷取完整 Cookie | | 速率限制 | 默认 5000 次 / 小时 / Token | 控制写入频率，必要时分批处理 |

文档 id（数字）≠ slug（URL 中那一段）。update / delete 走 id；get 两者均可。

本地开发与构建

如果你想在本地修改源码、调试或贡献代码：

git clone <this-repo>
cd yuque-mcp
npm install
npm run build      # 编译到 dist/
npm start          # node dist/index.js

手动握手测试（不接客户端）

(printf '%s\n%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'; sleep 1) \
  | YUQUE_COOKIE='你的cookie' node dist/index.js

tools/list 应返回上文表格中列出的全部工具。

发布新版本（维护者）

npm version patch          # 0.1.x → 0.1.(x+1)，自动 bump 并打 tag
npm publish --access public

prepublishOnly 钩子会自动执行 npm run build。

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@joren.li/yuque-mcp

目录

快速开始

鉴权方式

方式 A：Cookie（推荐）

方式 B：Personal Token

接入 Cursor

Cookie 模式（推荐）

Token 模式

接入 Claude Desktop

环境变量参考

提供的工具

常见用法

直接给链接，让模型自动读取

列表 → 定位 → 读取

写入文档

常见问题排查

本地开发与构建

手动握手测试（不接客户端）

发布新版本（维护者）

License