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 工具：

工具	说明
yuque_read	读取语雀文档，返回渲染后的文本内容。
yuque_read_markdown	推荐。读取语雀 Lake/API 源内容并转换为可读 Markdown，保留表格、PlantUML/Mermaid 图表、代码块、图片、链接和画板摘要。
yuque_list_docs	列出知识库中的所有文档。

技术栈：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 面板（推荐）

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

方法二：Console 命令

1. 登录 语雀
2. 按 F12 打开浏览器开发者工具
3. 在 Console 中输入：

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

4. 复制输出的值

⚠️ 如果 _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 留空。

环境变量

变量名	必填	默认值	说明
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）

常见问题

Session 无效 / 读取失败

重新登录语雀网站，获取新的 _yuque_session 值并更新配置。

Playwright 渲染失败

如果系统已安装 Chrome，可以设置 YUQUE_BROWSER_CHANNEL=chrome 以使用系统 Chrome，无需额外安装 Playwright 自带 Chromium。

Python 找不到

在配置中使用 Python 的完整路径作为 command，例如：

• macOS: /usr/bin/python3
• Windows: C:/Users/你的用户名/AppData/Local/Programs/Python/Python312/python.exe

团队/空间子域名

如果文档位于团队子域名下（如 ogtd9v.yuque.com），可以将 YUQUE_HOST 设为常用子域名；也可以直接传完整文档 URL，工具会从 URL 推导实际 host。

License

MIT License — 详见 LICENSE。

---

English Documentation

Features

Provides 3 MCP tools:

Tool	Description
yuque_read	Read a Yuque document and return the rendered text content.
yuque_read_markdown	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.
yuque_list_docs	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 chromium

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

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

Method 2: Console Command

1. Log in to Yuque
2. Press F12 to open browser DevTools
3. In the Console, run:

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

4. 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.

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 use python -m yuque_mcp as the command instead.

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

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/python3
• Windows: 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.