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（可选）列出知识库中的所有文档

安装#

bash

# 方式一：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 面板（推荐）

1. 登录 语雀
2. 按 F12 打开浏览器开发者工具
3. 切换到 Application（应用）面板
4. 左侧展开 Cookies → 点击 https://www.yuque.com
5. 找到 _yuque_session，复制其 Value 列的值

方法二：Console 命令

1. 登录 语雀

2. 按 F12 → 在 Console 中输入： javascript

   document.cookie.split('; ').find(c => c.startsWith('_yuque_session=')).split('=')[1]
   
   

3. 复制输出的值

⚠️ 如果 _yuque_session 被标记为 HttpOnly，方法二无效，请使用方法一。

Session 有效期约 30 天，过期后需重新获取。

配置 MCP 客户端#

在 MCP 客户端的配置文件中添加以下内容：

json

{
  "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.jsonClaude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.jsonCursor.cursor/mcp.json（项目根目录）WorkBuddyMCP 配置文件通用 MCP 客户端参考客户端文档

如果未通过 pip install 安装，可将 command 改为 python， args 设为 ["-m", "yuque_mcp"]。

环境变量#

变量名必填默认值说明YUQUE_SESSION是—语雀 Session Cookie（ _yuque_session 的值）YUQUE_HOST否https://www.yuque.com默认语雀主机，用于补全短路径 URLYUQUE_BROWSER_CHANNEL否—Playwright 浏览器通道，如 chrome``YUQUE_CHROMIUM_EXECUTABLE否—Chromium/Chrome 可执行文件绝对路径YUQUE_RENDER_MODE否auto渲染模式： auto（自动）、 off（关闭）、 force（强制 Playwright）

使用示例#

读取文档为 Markdown（推荐）：

text

帮我读取这个语雀文档：https://www.yuque.com/cc9c0g/rebell/hf0gch

列出知识库文档：

text

列出语雀知识库 cc9c0g/rebell 里的所有文档

读取渲染内容：

text

读取这个语雀页面的内容：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#

ToolParametersDescriptionyuque_read``url (required)Read a Yuque document and return the rendered text contentyuque_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 summariesyuque_list_docs``repo_slug (required), host (optional)List all documents in a Yuque repository

Installation#

bash

# 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)

1. Log in to Yuque
2. Press F12 to open browser DevTools
3. Switch to the Application tab
4. Expand Cookies → click https://www.yuque.com
5. Find _yuque_session and copy its Value

Method 2: Console Command

1. Log in to Yuque

2. Press F12 → in the Console, run: javascript

   document.cookie.split('; ').find(c => c.startsWith('_yuque_session=')).split('=')[1]
   
   

3. Copy the output value

⚠️ If _yuque_session is marked as HttpOnly, 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:

json

{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "env": {
        "YUQUE_SESSION": "YOUR_YUQUE_SESSION",
        "YUQUE_HOST": "https://www.yuque.com"
      }
    }
  }
}

Configuration file locations by client:

ClientConfig File PathClaude Desktop (macOS)~/Library/Application Support/Claude/claude_desktop_config.jsonClaude Desktop (Windows)%APPDATA%\Claude\claude_desktop_config.jsonCursor.cursor/mcp.json (project root)WorkBuddyMCP configuration fileGeneric MCP ClientRefer to client documentation

If not installed via pip install, set command to python and args to ["-m", "yuque_mcp"].

Environment Variables#

VariableRequiredDefaultDescriptionYUQUE_SESSIONYes—Yuque session cookie ( _yuque_session value)YUQUE_HOSTNohttps://www.yuque.comDefault Yuque host for short-path URL completionYUQUE_BROWSER_CHANNELNo—Playwright browser channel, e.g. chrome``YUQUE_CHROMIUM_EXECUTABLENo—Absolute path to a Chromium/Chrome executableYUQUE_RENDER_MODENoautoRendering mode: auto, off, or force

Usage Examples#

Read a document as Markdown (recommended):

text

Read this Yuque document: https://www.yuque.com/cc9c0g/rebell/hf0gch

List documents in a knowledge base:

text

List all documents in Yuque repository cc9c0g/rebell

Read rendered content:

text

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