yuque-md-mcp

语雀 Markdown MCP Server — 将语雀文档导出为原生 Markdown 文件，模拟点击「复制为 Markdown」按钮的效果。

Yuque Markdown MCP Server — Export Yuque documents as native Markdown files, simulating the "Copy as Markdown" button.

功能 / Features

| 工具 / Tool | 说明 / Description | |---|---| | yuque_export_md | 导出语雀文档为本地 .md 文件 / Export Yuque doc as local .md file | | yuque_get_doc | 获取文档的 Markdown 内容（从 lake 格式转换） / Get doc content as Markdown | | yuque_list_repos | 列出所有知识库（个人 + 团队空间） / List all knowledge bases | | yuque_get_toc | 获取知识库文档目录树 / Get document tree of a knowledge base | | yuque_search | 搜索语雀文档 / Search Yuque documents | | yuque_auth_status | 检查登录状态 / Check auth status | | yuque_refresh_cookie | 刷新登录 Cookie / Refresh login cookie |

Lake 格式完整转换： 标题 (h1-h6)、加粗/斜体/删除线/行内代码、链接、图片卡片、附件卡片、列表、表格、代码块、HTML 实体等。

Full lake-to-markdown conversion: headings, bold/italic/strikethrough/inline code, links, image cards, attachment cards, lists, tables, code blocks, HTML entities.

安装 / Installation

npm install -g yuque-md-mcp

Or use directly with npx:

npx yuque-md-mcp

配置 / Configuration

Claude Code

方式一：全局配置 (Way 1: Global config)

编辑 ~/.claude.json，在 mcpServers 中添加：

Edit ~/.claude.json, add to mcpServers:

{
  "mcpServers": {
    "yuque-md": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "yuque-md-mcp"]
    }
  }
}

方式二：项目级 .mcp.json (Way 2: Project-level)

在项目根目录创建 .mcp.json：

Create .mcp.json in your project root:

{
  "mcpServers": {
    "yuque-md": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "yuque-md-mcp"]
    }
  }
}

Cursor

编辑 Cursor 的 MCP 配置（Cursor Settings → MCP → Add new MCP server）：

Edit Cursor's MCP config (Cursor Settings → MCP → Add new MCP server):

{
  "mcpServers": {
    "yuque-md": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "yuque-md-mcp"]
    }
  }
}

注意 / Note: 如果 Cursor 的 MCP 配置路径不同，也可以直接在项目目录下创建 .mcp.json 文件，Cursor 会自动识别。

登录 / Login

首次使用需要设置语雀 Cookie，有两种方式：

First-time setup — your Yuque cookies are required. Two options:

方式一：从浏览器获取 (Way 1: From browser)

1. 在浏览器中登录 语雀 / Login to Yuque in browser
2. 打开 DevTools (F12) → Console
3. 粘贴并运行 / Paste and run:

copy(JSON.stringify({
  cookies: document.cookie.split('; ').map(c => ({
    name: c.split('=')[0],
    value: c.split('=').slice(1).join('='),
    domain: location.hostname,
    path: '/'
  })),
  expiresAt: new Date(Date.now() + 14 * 86400000).toISOString()
}))

4. 将剪贴板内容保存到 ~/.yuque-md-mcp/cookies.json / Save clipboard content to ~/.yuque-md-mcp/cookies.json

方式二：从 yuque-cookie-mcp 复制 (Way 2: Copy from yuque-cookie-mcp)

如果你已经配置过 yuque-cookie-mcp，直接复制 Cookie 文件：

If you already use yuque-cookie-mcp, just copy:

mkdir -p ~/.yuque-md-mcp
cp ~/.yuque-mcp/cookies.json ~/.yuque-md-mcp/cookies.json

使用示例 / Usage Examples

# 获取文档的 Markdown 内容
# Get doc as Markdown
yuque_get_doc --url https://sxjy1211.yuque.com/org-wiki-sxjy1211-pydxbt/nhuznl/docslug

# 导出文档为 .md 文件
# Export doc as .md file
yuque_export_md --url https://sxjy1211.yuque.com/org-wiki-sxjy1211-pydxbt/nhuznl/docslug --outputDir ./docs

# 列出所有知识库
# List all knowledge bases
yuque_list_repos

# 获取知识库目录
# Get knowledge base TOC
yuque_get_toc --bookId 123456 --domain https://sxjy1211.yuque.com

# 搜索文档
# Search documents
yuque_search --query "需求文档"

# 检查登录状态
# Check auth status
yuque_auth_status

在支持 MCP 的 AI 工具（Claude Code、Cursor 等）中，直接用自然语言描述需求即可：

In MCP-compatible AI tools (Claude Code, Cursor, etc.), just describe what you want:

"导出这个语雀文档为 Markdown 文件" / "Export this Yuque doc as Markdown" "列出我的语雀知识库" / "List my Yuque knowledge bases"

支持平台 / Supported Platforms

| 平台 / Platform | 支持 / Support | |---|---| | Claude Code (CLI) | Yes | | Claude Desktop | Yes | | Cursor | Yes | | VS Code + Claude Extension | Yes | | 任何支持 MCP 协议的工具 / Any MCP-compatible tool | Yes |

原理 / How it works

1. 使用 Cookie 认证访问语雀页面 / Uses cookie auth to access Yuque pages
2. 从页面 HTML 中解析 appData 获取 book_id 和文档 slug / Parses appData from page HTML
3. 调用语雀内部 API /api/docs/{slug}?book_id={id} 获取 lake 格式内容 / Calls internal API for lake format content
4. 将 lake 格式（HTML-like）转换为标准 Markdown / Converts lake format to standard Markdown

不依赖语雀 Open API（无需付费），支持个人空间和企业空间。

No dependency on Yuque Open API (no payment needed). Works for both personal and org spaces.

License

MIT