yuque
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yuque list documents in my project knowledge base"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Yuque MCP Tool
一个基于 Session Cookie 的语雀 MCP (Model Context Protocol) 服务器,让你可以在 Claude Desktop、Cursor、WorkBuddy 等 AI 客户端中直接读取语雀文档。
A Model Context Protocol (MCP) server for reading Yuque documents via session cookie, compatible with Claude Desktop, Cursor, WorkBuddy, and other MCP clients.
中文文档
功能特性
提供 3 个 MCP 工具:
工具 | 说明 |
| 读取语雀文档,返回渲染后的文本内容。 |
| 推荐。读取语雀 Lake/API 源内容并转换为可读 Markdown,保留表格、PlantUML/Mermaid 图表、代码块、图片、链接和画板摘要。 |
| 列出知识库中的所有文档。 |
技术栈:aiohttp + Playwright(可选渲染)+ BeautifulSoup4
快速开始
1. 安装
pip install yuque-mcp-tool
# 如果需要 Playwright 渲染功能(推荐)
python -m playwright install chromium或者从源码安装:
git clone https://github.com/andy8663/yuque-mcp-tool.git
cd yuque-mcp-tool
pip install -e .2. 获取 Session Cookie
方法一:Application 面板(推荐)
登录 语雀
按
F12打开浏览器开发者工具切换到 Application(应用)面板
左侧展开 Cookies → 点击
https://www.yuque.com在 Cookie 列表中找到
_yuque_session,复制其 Value 列的值
方法二:Console 命令
登录 语雀
按
F12打开浏览器开发者工具在 Console 中输入:
document.cookie.split('; ').find(c => c.startsWith('_yuque_session=')).split('=')[1]复制输出的值
⚠️ 如果
_yuque_session被标记为HttpOnly,方法二将无法读取,请使用方法一。Session Cookie 有效期约 30 天,过期后需重新获取。
3. 配置 MCP 客户端
根据你使用的客户端,选择对应的配置方式(见下方配置示例)。
配置示例
Claude Desktop
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或 %APPDATA%\Claude\claude_desktop_config.json(Windows):
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}Cursor
编辑项目根目录下的 .cursor/mcp.json:
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}WorkBuddy
在 WorkBuddy 的 MCP 配置文件中添加:
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}通用 MCP 客户端
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}如果未通过
pip install安装,也可以使用python -m yuque_mcp作为command,args留空。
环境变量
变量名 | 必填 | 默认值 | 说明 |
| 是 | — | 语雀 Session Cookie( |
| 否 |
| 默认语雀主机地址,用于补全短路径 URL |
| 否 | — | Playwright 浏览器通道,如 |
| 否 | — | Chromium/Chrome 可执行文件的绝对路径 |
| 否 |
| 渲染模式: |
常见问题
Session 无效 / 读取失败
重新登录语雀网站,获取新的 _yuque_session 值并更新配置。
Playwright 渲染失败
如果系统已安装 Chrome,可以设置 YUQUE_BROWSER_CHANNEL=chrome 以使用系统 Chrome,无需额外安装 Playwright 自带 Chromium。
Python 找不到
在配置中使用 Python 的完整路径作为 command,例如:
macOS:
/usr/bin/python3Windows:
C:/Users/你的用户名/AppData/Local/Programs/Python/Python312/python.exe
团队/空间子域名
如果文档位于团队子域名下(如 ogtd9v.yuque.com),可以将 YUQUE_HOST 设为常用子域名;也可以直接传完整文档 URL,工具会从 URL 推导实际 host。
License
MIT License — 详见 LICENSE。
Related MCP server: Yuque MCP Server
English Documentation
Features
Provides 3 MCP tools:
Tool | Description |
| Read a Yuque document and return the rendered text content. |
| Recommended. Read the Yuque Lake/API source content and convert it to readable Markdown, preserving tables, PlantUML/Mermaid diagrams, code blocks, images, links, and board summaries. |
| List all documents in a Yuque knowledge base. |
Tech stack: aiohttp + Playwright (optional rendering) + BeautifulSoup4
Quick Start
1. Installation
pip install yuque-mcp-tool
# If you need Playwright rendering (recommended)
python -m playwright install chromiumOr install from source:
git clone https://github.com/andy8663/yuque-mcp-tool.git
cd yuque-mcp-tool
pip install -e .2. Get Your Session Cookie
Method 1: Application Panel (Recommended)
Log in to Yuque
Press
F12to open browser DevToolsSwitch to the Application tab
Expand Cookies in the left sidebar → click
https://www.yuque.comFind
_yuque_sessionin the cookie list and copy its Value
Method 2: Console Command
Log in to Yuque
Press
F12to open browser DevToolsIn the Console, run:
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.
3. Configure Your MCP Client
Choose the configuration for your client below.
Configuration Examples
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}Cursor
Edit .cursor/mcp.json in your project root:
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}WorkBuddy
Add to your WorkBuddy MCP configuration:
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}Generic MCP Client
{
"mcpServers": {
"yuque": {
"command": "yuque-mcp",
"env": {
"YUQUE_SESSION": "YOUR_YUQUE_SESSION",
"YUQUE_HOST": "https://www.yuque.com"
}
}
}
}If you haven't installed via
pip install, you can usepython -m yuque_mcpas thecommandinstead.
Environment Variables
Variable | Required | Default | Description |
| Yes | — | Yuque session cookie ( |
| No |
| Default Yuque host for short-path URL completion |
| No | — | Playwright browser channel, e.g. |
| No | — | Absolute path to a Chromium/Chrome executable |
| No |
| Rendering mode: |
FAQ
Invalid Session / Read Failure
Re-log in to Yuque, obtain a new _yuque_session value, and update your configuration.
Playwright Rendering Failure
If Chrome is installed on your system, set YUQUE_BROWSER_CHANNEL=chrome to use the system Chrome without installing Playwright's bundled Chromium.
Python Not Found
Use the full path to your Python executable as the command in your configuration:
macOS:
/usr/bin/python3Windows:
C:/Users/your-username/AppData/Local/Programs/Python/Python312/python.exe
Team / Workspace Subdomains
If your documents are on a team subdomain (e.g. ogtd9v.yuque.com), set YUQUE_HOST to your common subdomain. You can also pass full document URLs directly — the tool derives the actual host from the URL.
License
MIT License — see LICENSE.
Available Tools
3 toolsyuque_list_docsB
List all documents in a Yuque repository
Inputs: repo_slug (required), host.
yuque_readA
Read a Yuque document by URL. Returns the full rendered content.
Inputs: url (required).
yuque_read_markdownA
Read a Yuque document by URL using Yuque Lake/API source content and convert it to readable Markdown with tables, PlantUML, Mermaid, code blocks, images, links, and board summaries.
Inputs: url (required), include_stats.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The three tools are distinct: one lists documents, and two read documents in different formats. However, the two read tools have overlapping purposes (both read a document by URL), which could cause minor confusion.
All tools share a 'yuque_' prefix and use verb_noun for most, but 'yuque_read' lacks a noun suffix, creating slight inconsistency with 'yuque_list_docs' and 'yuque_read_markdown'.
With only 3 tools, the server is severely under-scoped for a platform like Yuque, which typically requires many more operations (create, update, delete, etc.).
The server only provides read and list functionality, missing essential CRUD operations. It is extremely incomplete for the Yuque domain.
Related MCP Connectors
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
Documents to Markdown/PDF, OCR, video and audio transcripts, TTS, screenshots, domains, frames.
Parse PDF/Word/PPT/HTML to Markdown; tables as JSON, image extraction, RAG chunking, page ranges.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Yuque (语雀) knowledge base platform through their API. Supports document management, search, and repository operations including creating, reading, updating, and deleting documents in multiple formats.928 npm3MIT
- AlicenseBqualityDmaintenanceEnables access to Yuque (语雀) documentation through cookie-based authentication, supporting document retrieval, search, TOC navigation, and content management from knowledge bases via URL or namespace.4731 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Yuque (语雀) platform through MCP protocol, supporting knowledge base management, document operations, search, and team collaboration features.11MIT
- AlicenseCqualityDmaintenanceEnables to interact with Yuque knowledge base API through MCP. Supports discovering, reading, creating, updating, deleting docs and repos, managing groups and members, and using Yuque content as a research knowledge base.2837 npmMIT