Skip to main content
Glama

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 .

方法一: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。


Related MCP server: Yuque MCP Server

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 .

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.

Available Tools

3 tools
yuque_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

    B3.2/5.0

    Scored across 3 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

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

    Tool Count2/5

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

    Completeness1/5

    The server only provides read and list functionality, missing essential CRUD operations. It is extremely incomplete for the Yuque domain.

    Related MCP Connectors

    Related MCP Servers