Yuque MCP Tool

中文文档

简介

Yuque MCP Tool 是一个基于 Session Cookie 的语雀 MCP (Model Context Protocol) 服务器。安装后，AI Agent 可以直接读取你的语雀文档内容，无需手动复制粘贴。

适用场景：
- 让 AI 读取语雀知识库中的技术文档、产品需求、会议纪要
- 将语雀文档批量转换为 Markdown 格式
- 快速浏览知识库的文档目录结构

提供的工具

安装

# 方式一：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 客户端的配置文件中添加以下内容：

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

各客户端配置文件位置：

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

环境变量

使用示例

读取文档为 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

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)

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:

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

Configuration file locations by client:

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

Environment Variables

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