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

技术栈：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 留空。

环境变量

常见问题

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。

Related MCP server: Yuque MCP Server

English Documentation

Features

Provides 3 MCP tools:

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

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.