通过 MCP 协议在 AI 客户端中读取语雀文档。支持读取渲染内容、转换 Markdown、列出知识库文档。 兼容 Claude Desktop、Cursor、WorkBuddy 等主流 MCP 客户端。
Yuque MCP Tool
中文文档
简介
Yuque MCP Tool 是一个基于 Session Cookie 的语雀 MCP (Model Context Protocol) 服务器。安装后,AI Agent 可以直接读取你的语雀文档内容,无需手动复制粘贴。
适用场景:
- 让 AI 读取语雀知识库中的技术文档、产品需求、会议纪要
- 将语雀文档批量转换为 Markdown 格式
- 快速浏览知识库的文档目录结构
提供的工具
| 工具名 | 参数 | 说明 |
|---|---|---|
yuque_read | url(必填) | 读取语雀文档,返回渲染后的文本内容 |
yuque_read_markdown | url(必填),include_stats(可选,布尔值) | 推荐。读取 Lake/API 源内容并转换为 Markdown,保留表格、PlantUML/Mermaid 图表、代码块、图片、链接和画板摘要 |
yuque_list_docs | repo_slug(必填),host(可选) | 列出知识库中的所有文档 |
安装
# 方式一:pip 安装(推荐)
pip install yuque-mcp-tool
# 安装 Playwright 浏览器(可选,用于渲染 JS 页面)
python -m playwright install chromium
# 方式二:从源码安装
git clone https://github.com/andy8663/yuque-mcp-tool.git
cd yuque-mcp-tool
pip install -e .
获取语雀 Session Cookie
方法一:Application 面板(推荐)
- 登录 语雀
- 按
F12打开浏览器开发者工具 - 切换到 Application(应用)面板
- 左侧展开 Cookies → 点击
https://www.yuque.com - 找到
_yuque_session,复制其 Value 列的值
方法二:Console 命令
- 登录 语雀
- 按
F12→ 在 Console 中输入:javascript document.cookie.split('; ').find(c => c.startsWith('_yuque_session=')).split('=')[1] - 复制输出的值
⚠️ 如果
_yuque_session被标记为HttpOnly,方法二无效,请使用方法一。Session 有效期约 30 天,过期后需重新获取。
配置 MCP 客户端
在 MCP 客户端的配置文件中添加以下内容:
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}
各客户端配置文件位置:
| 客户端 | 配置文件路径 |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | .cursor/mcp.json(项目根目录) |
| WorkBuddy | MCP 配置文件 |
| 通用 MCP 客户端 | 参考客户端文档 |
如果未通过
pip install安装,可将command改为python,args设为["-m", "yuque_mcp"]。
环境变量
| 变量名 | 必填 | 默认值 | 说明 |
|---|---|---|---|
YUQUE_SESSION | 是 | — | 语雀 Session Cookie(_yuque_session 的值) |
YUQUE_HOST | 否 | https://www.yuque.com | 默认语雀主机,用于补全短路径 URL |
YUQUE_BROWSER_CHANNEL | 否 | — | Playwright 浏览器通道,如 chrome |
YUQUE_CHROMIUM_EXECUTABLE | 否 | — | Chromium/Chrome 可执行文件绝对路径 |
YUQUE_RENDER_MODE | 否 | auto | 渲染模式:auto(自动)、off(关闭)、force(强制 Playwright) |
使用示例
读取文档为 Markdown(推荐):
帮我读取这个语雀文档:https://www.yuque.com/cc9c0g/rebell/hf0gch
列出知识库文档:
列出语雀知识库 cc9c0g/rebell 里的所有文档
读取渲染内容:
读取这个语雀页面的内容:https://ogtd9v.yuque.com/org/wiki/hf0gch
常见问题
Session 无效 / 读取失败:重新登录语雀,获取新的 _yuque_session 值并更新配置。
Playwright 渲染失败:设置 YUQUE_BROWSER_CHANNEL=chrome 使用系统 Chrome。
团队/空间子域名:文档在团队子域名下(如 ogtd9v.yuque.com)时,设置 YUQUE_HOST 为常用子域名,或直接传完整 URL。
技术栈
aiohttp + Playwright(可选渲染)+ BeautifulSoup4
License
MIT License — 详见 LICENSE
English Documentation
Overview
Yuque MCP Tool is a session-cookie-based MCP (Model Context Protocol) server for Yuque documents. Once installed, your AI Agent can read Yuque documents directly — no manual copy-paste needed.
Use cases:
- Let AI read technical docs, product requirements, and meeting notes from Yuque
- Batch convert Yuque documents to Markdown format
- Quickly browse the document tree of a knowledge base
Available Tools
| Tool | Parameters | Description |
|---|---|---|
yuque_read | url (required) | Read a Yuque document and return the rendered text content |
yuque_read_markdown | url (required), include_stats (optional, boolean) | Recommended. Read the Lake/API source content and convert to Markdown, preserving tables, PlantUML/Mermaid diagrams, code blocks, images, links, and board summaries |
yuque_list_docs | repo_slug (required), host (optional) | List all documents in a Yuque repository |
Installation
# Option 1: pip install (recommended)
pip install yuque-mcp-tool
# Install Playwright browser (optional, for JS page rendering)
python -m playwright install chromium
# Option 2: install from source
git clone https://github.com/andy8663/yuque-mcp-tool.git
cd yuque-mcp-tool
pip install -e .
Getting Your Session Cookie
Method 1: Application Panel (Recommended)
- Log in to Yuque
- Press
F12to open browser DevTools - Switch to the Application tab
- Expand Cookies → click
https://www.yuque.com - Find
_yuque_sessionand copy its Value
Method 2: Console Command
- Log in to Yuque
- Press
F12→ in the Console, run:javascript document.cookie.split('; ').find(c => c.startsWith('_yuque_session=')).split('=')[1] - Copy the output value
⚠️ If
_yuque_sessionis marked asHttpOnly, Method 2 will not work — use Method 1 instead.The session cookie is valid for approximately 30 days.
MCP Client Configuration
Add the following to your MCP client's configuration file:
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}
Configuration file locations by client:
| Client | Config File Path |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | .cursor/mcp.json (project root) |
| WorkBuddy | MCP configuration file |
| Generic MCP Client | Refer to client documentation |
If not installed via
pip install, setcommandtopythonandargsto["-m", "yuque_mcp"].
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
YUQUE_SESSION | Yes | — | Yuque session cookie (_yuque_session value) |
YUQUE_HOST | No | https://www.yuque.com | Default Yuque host for short-path URL completion |
YUQUE_BROWSER_CHANNEL | No | — | Playwright browser channel, e.g. chrome |
YUQUE_CHROMIUM_EXECUTABLE | No | — | Absolute path to a Chromium/Chrome executable |
YUQUE_RENDER_MODE | No | auto | Rendering mode: auto, off, or force |
Usage Examples
Read a document as Markdown (recommended):
Read this Yuque document: https://www.yuque.com/cc9c0g/rebell/hf0gch
List documents in a knowledge base:
List all documents in Yuque repository cc9c0g/rebell
Read rendered content:
Read the content of this Yuque page: https://ogtd9v.yuque.com/org/wiki/hf0gch
FAQ
Invalid Session / Read Failure: Re-log in to Yuque, obtain a new _yuque_session value, and update your configuration.
Playwright Rendering Failure: Set YUQUE_BROWSER_CHANNEL=chrome to use the system Chrome.
Team / Workspace Subdomains: If documents are on a team subdomain (e.g. ogtd9v.yuque.com), set YUQUE_HOST to your common subdomain, or pass full document URLs directly.
Tech Stack
aiohttp + Playwright (optional rendering) + BeautifulSoup4
License
MIT License — see LICENSE
- Downloads
- 513All time
- Security audit
- Review
- Last updated
- 5mo ago
- Current version
- v0.1.0
- License
- MIT-0
