语雀 MCP Server

这是一个用于 Cursor 的语雀 MCP (Model Context Protocol) 服务器，可以让你在 Cursor 中直接通过语雀 URL 或知识库命名空间获取文档信息。

📌 环境变量快速参考

环境变量	必需	默认值	说明
`YUQUE_COOKIE`	✅	无	语雀 Cookie（单个 session 或完整 Cookie 字符串）
`YUQUE_BASE_URL`	❌	`https://www.yuque.com`	语雀基础 URL（企业私有部署需要）
`YUQUE_NAMESPACE`	❌	无	默认知识库命名空间（如 `username/repo`，支持中文）

快速配置示例：

# .env 文件
YUQUE_COOKIE=your-cookie-here
YUQUE_BASE_URL=https://your-company.yuque.com  # 企业用户需要
YUQUE_NAMESPACE=username/repo                    # 可选

功能特性

✨ 核心功能:

📋 通过语雀 URL 或命名空间+slug 获取文档详情
🔍 在知识库中搜索文档（标题和描述匹配）
📚 获取知识库完整目录结构（TOC）
📝 列出知识库所有文档
🍪 基于 Cookie 认证，免费用户可用

认证方式与实现

本服务器使用 Cookie 认证 + 无头浏览器的方式获取语雀文档：

✅ 使用 Puppeteer 无头浏览器模拟真实浏览器访问
✅ 通过设置 Cookie 自动登录
✅ 直接从页面提取文档内容
✅ 绕过 API 权限限制
✅ 无需语雀超级会员

语雀 MCP 支持两种 Cookie 配置方式：

方式一：仅使用 `_yuque_session`（推荐，简单）

登录语雀网站（如 https://www.yuque.com 或企业私有部署地址）
打开浏览器开发者工具（按 F12 或右键 → 检查）
切换到 Application（应用）或存储标签
在左侧找到 Cookies → 对应的语雀域名
找到名为 _yuque_session 的 Cookie
复制它的值（Value 列）

登录语雀网站后，打开浏览器开发者工具（F12）
切换到 Network（网络）标签
刷新页面或访问任意语雀文档
点击任意请求，找到 Request Headers（请求头）
找到 Cookie: 字段，复制完整的 Cookie 字符串

完整 Cookie 示例格式：

lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx; current_theme=default; acw_tc=xxx

⚠️ 注意:

Cookie 会过期（通常几天到几周），过期后需要重新获取

使用完整 Cookie 字符串通常更稳定，但包含更多敏感信息，请妥善保管

安装步骤

1. 安装依赖

cd yuque-mcp
npm install

2. 配置环境变量

在项目根目录创建 .env 文件。你可以复制 env.example 文件作为模板：

cp env.example .env

然后编辑 .env 文件，填入你的配置：

# 语雀 Cookie（必需）
# 方式一：仅 _yuque_session 的值
YUQUE_COOKIE=n_FzpQWqYiQEgGAKM6Y9BYtxBrmoJD16z6Jfv4wlFVvUy3_O621jF6Gg9_6R59pueqqvebZW7EC6tqPoU6qD9A==

# 方式二：完整 Cookie 字符串（推荐，更稳定）
# YUQUE_COOKIE=lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx; current_theme=default

# 可选：语雀基础 URL（企业私有部署时需要）
# 公有云用户可以不设置，默认为 https://www.yuque.com
# YUQUE_BASE_URL=https://your-company.yuque.com

# 可选：设置默认知识库命名空间
# 设置后可以直接通过 slug 获取文档，无需每次指定命名空间
# 支持中文用户名，例如：username/repo 或 用户名/知识库名
# YUQUE_NAMESPACE=username/repo

💡 项目中提供了 env.example 模板文件，包含详细的配置说明

环境变量详细说明:

环境变量	是否必需	说明	示例
`YUQUE_COOKIE`	✅ 必需	从浏览器获取的 Cookie，可以是单个 `_yuque_session` 的值，也可以是完整的 Cookie 字符串	见上方示例
`YUQUE_BASE_URL`	❌ 可选	语雀服务地址，企业私有部署时需要设置	`https://company.yuque.com`
`YUQUE_NAMESPACE`	❌ 可选	默认知识库命名空间，格式为 `username/repo`，支持中文	`张三/我的知识库`

配置建议：

公有云用户：只需配置 YUQUE_COOKIE
企业用户：需要同时配置 YUQUE_COOKIE 和 YUQUE_BASE_URL
常用知识库：建议配置 YUQUE_NAMESPACE，简化后续操作

3. 构建项目

npm run build

4. 完整配置示例

以下是不同场景下的完整配置示例：

场景一：公有云个人用户（最简单）

.env 文件：

YUQUE_COOKIE=n_FzpQWqYiQEgGAKM6Y9BYtxBrmoJD16z6Jfv4wlFVvUy3_O621jF6Gg9_6R59pueqqvebZW7EC6tqPoU6qD9A==

mcp.json 文件：

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"]
    }
  }
}

场景二：企业私有部署（推荐配置）

.env 文件：

# 企业语雀地址
YUQUE_BASE_URL=https://your-company.yuque.com

# 完整 Cookie 字符串（更稳定）
YUQUE_COOKIE=lang=zh-cn; _yuque_session=your-session-here; yuque_ctoken=your-token-here; current_theme=default

# 默认知识库（支持中文）
YUQUE_NAMESPACE=username/your-repo-name

mcp.json 文件：

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"]
    }
  }
}

场景三：直接在 mcp.json 中配置（无需 .env）

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"],
      "env": {
        "YUQUE_BASE_URL": "https://your-company.yuque.com",
        "YUQUE_COOKIE": "lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx",
        "YUQUE_NAMESPACE": "username/your-repo-name"
      }
    }
  }
}

💡 提示：推荐使用场景二（.env 文件），因为更新 Cookie 时无需修改 mcp.json

配置 Cursor MCP

Cursor 配置文件位置

macOS: ~/.cursor/mcp.json 或 ~/.config/cursor/mcp.json
Linux: ~/.config/cursor/mcp.json
Windows: %APPDATA%\cursor\mcp.json

方式一：使用 .env 文件（推荐）

在项目目录下创建 .env 文件配置环境变量，然后编辑 Cursor 的 mcp.json：

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": [
        "/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
      ]
    }
  }
}

优点：

✅ 环境变量集中管理，便于更新
✅ 配置文件更简洁
✅ 敏感信息不暴露在 mcp.json 中

方式二：直接在 mcp.json 中配置环境变量

适合不想创建额外文件的场景：

公有云配置示例（最简单）

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": [
        "/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
      ],
      "env": {
        "YUQUE_COOKIE": "your-session-cookie-value-here"
      }
    }
  }
}

企业私有部署配置示例

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": [
        "/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
      ],
      "env": {
        "YUQUE_BASE_URL": "https://your-company.yuque.com",
        "YUQUE_COOKIE": "lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx",
        "YUQUE_NAMESPACE": "username/repo"
      }
    }
  }
}

注意事项：

⚠️ 路径必须使用绝对路径
⚠️ Windows 用户注意路径分隔符，使用 \\ 或 /
⚠️ Cookie 中如果包含特殊字符，确保正确转义
⚠️ YUQUE_NAMESPACE 支持中文，如 "用户名/知识库名"

启动服务

保存配置文件
重启 Cursor 使配置生效
在 Cursor 中，你应该能看到 Yuque MCP 服务已连接

使用方法

配置完成后，重启 Cursor，你就可以在 Cursor 中使用语雀 MCP 服务了。

示例 1: 获取文档详情

在 Cursor 中输入:

请帮我获取这个语雀文档的信息：https://www.yuque.com/username/repo/doc-slug

或者如果你设置了默认知识库命名空间:

请帮我查看文档 doc-slug 的内容

示例 2: 搜索文档

请在语雀知识库 username/repo 中搜索包含"API"的文档

示例 3: 获取知识库目录

请显示 username/repo 这个知识库的目录结构

示例 4: 列出所有文档

请列出 username/repo 知识库中的所有文档

MCP 工具说明

1. get-yuque-doc

获取单个语雀文档的详细信息。

参数:

docUrl (string, 可选): 语雀文档 URL
namespace (string, 可选): 知识库命名空间，格式为 username/repo
slug (string, 可选): 文档 slug

支持的调用方式:

// 方式 1: 使用 URL
{ docUrl: "https://www.yuque.com/username/repo/doc-slug" }

// 方式 2: 使用命名空间 + slug
{ namespace: "username/repo", slug: "doc-slug" }

// 方式 3: 如果设置了默认命名空间，只需提供 slug
{ slug: "doc-slug" }

返回信息:

文档基本信息（标题、ID、格式、字数等）
作者信息
知识库信息
文档完整内容（Markdown 或 HTML）
统计数据（浏览量、点赞数、评论数）

2. get-yuque-toc

获取知识库的完整目录结构。

参数:

namespace (string, 可选): 知识库命名空间，如果未提供则使用默认命名空间

返回信息:

知识库基本信息
完整的文档目录树
每个文档的标题和 slug

3. search-yuque-docs

在知识库中搜索文档。

参数:

query (string, 必需): 搜索关键词
namespace (string, 可选): 知识库命名空间，如果未提供则使用默认命名空间

返回信息:

匹配的文档列表
每个文档的基本信息

📝 说明: 搜索会在文档标题和描述中进行关键词匹配（不区分大小写）。

4. list-yuque-docs

列出知识库中的所有文档。

参数:

namespace (string, 可选): 知识库命名空间，如果未提供则使用默认命名空间

返回信息:

知识库基本信息
所有文档的列表
每个文档的基本信息

项目结构

yuque-mcp/
├── src/
│   ├── index.ts           # MCP 服务器入口
│   └── lib/
│       ├── api.ts         # 语雀 API 调用
│       ├── browser-api.ts # 无头浏览器实现
│       ├── types.ts       # TypeScript 类型定义
│       └── utils.ts       # 工具函数
├── dist/                  # 编译输出目录
├── package.json
├── tsconfig.json
├── env.example            # 环境变量配置模板
├── .env                   # 环境变量配置（需基于 env.example 创建）
└── README.md

重要文件说明：

env.example: 环境变量配置模板，包含详细注释
.env: 实际使用的环境变量文件（需自行创建，不要提交到 git）
src/lib/browser-api.ts: 使用 Puppeteer 实现的无头浏览器方案
dist/: TypeScript 编译后的 JavaScript 文件

开发命令

# 安装依赖
npm install

# 构建
npm run build

# 开发模式（构建并运行）
npm run dev

# 格式化代码
npm run format

故障排除

1. 认证失败

症状: 提示 "语雀配置验证失败" 或 "Cookie 已过期"

解决方法:

✅ 检查 YUQUE_COOKIE 是否正确
✅ Cookie 可能已过期，重新从浏览器获取
✅ 确保已登录语雀网站
✅ 尝试使用完整 Cookie 字符串而不是仅 _yuque_session
✅ 企业用户检查 YUQUE_BASE_URL 是否配置正确
✅ 尝试清除浏览器缓存后重新登录，再获取新 Cookie

2. 无法获取文档

症状: 提示 "无法获取文档" 或 "文档不存在"

检查项:

✅ 文档 URL 或命名空间是否正确
✅ 文档是否为私有文档（需要登录后才能访问）
✅ 你的语雀账号是否有权限访问该文档
✅ Cookie 是否有效
✅ 企业用户：确认 YUQUE_BASE_URL 与实际访问的域名一致
✅ 如果使用了 YUQUE_NAMESPACE，确认格式正确（支持中文）

3. Cursor 无法找到 MCP 服务

检查项:

✅ 检查 mcp.json 中的路径是否正确（必须是绝对路径）
✅ 确保已经运行 npm run build 构建项目
✅ 检查 dist/index.js 文件是否存在
✅ 重启 Cursor
✅ 查看 Cursor 的 MCP 日志，确认服务是否启动成功

Cookie 的有效期取决于语雀的设置，通常：

如果勾选了"记住我"：几周到几个月
如果没有勾选：几天到一周

建议：

在 .env 文件中保存 Cookie，过期后只需更新文件中的值
使用完整 Cookie 字符串通常比单独的 _yuque_session 有效期更长
定期（如每周）检查并更新 Cookie

5. 企业私有部署特殊问题

症状: 公有云配置正常，但企业内部部署无法访问

解决方法:

✅ 确认设置了正确的 YUQUE_BASE_URL
✅ URL 格式应为 https://your-company.yuque.com（不带尾部斜杠）
✅ 确认网络可以访问该地址（可能需要 VPN）
✅ Cookie 必须从对应的企业语雀域名获取，不能混用

6. 中文命名空间无法识别

症状: 使用中文用户名或知识库名时报错

解决方法:

✅ YUQUE_NAMESPACE 支持中文，格式如："用户名/知识库名"
✅ 确保配置文件使用 UTF-8 编码
✅ 如果仍有问题，尝试使用 URL 中显示的英文 slug 代替中文名

安全建议

⚠️ 重要提示:

❌ 不要在代码仓库中提交包含真实 Cookie 的配置文件
❌ 不要在公开的 GitHub 等平台分享包含 Cookie 的配置
⚠️ Cookie 相当于你的登录凭证，泄露后他人可以访问你的语雀账号
🔄 定期更新 Cookie（建议每月至少一次）
🚨 如果 Cookie 泄露，立即退出语雀所有设备的登录

环境变量管理最佳实践

使用 .env 文件（推荐）

# 在项目根目录创建 .env 文件
# 添加到 .gitignore 防止提交
echo ".env" >> .gitignore

在 mcp.json 中配置
- mcp.json 通常在用户目录下（~/.cursor/mcp.json），不会被 git 追踪
- 但要注意备份时不要泄露
企业用户额外注意
- 企业语雀可能有更严格的安全策略
- 定期检查会话状态
- 考虑使用只读权限的账号

.gitignore 配置示例

如果你的项目使用 git，确保添加以下内容到 .gitignore：

# 环境变量
.env
.env.local
.env.*.local

# 配置文件（如果包含敏感信息）
*-config.json
mcp.json

与 Jira MCP 的对比

特性	Jira MCP	Yuque MCP
认证方式	Personal Access Token	Session Cookie
免费用户	✅ 可用	✅ 可用
Token 有效期	永久或自定义	几天到几周
配置难度	简单	简单
需要手动更新	❌	✅ (Cookie 过期时)

技术栈

TypeScript: 类型安全的 JavaScript
@modelcontextprotocol/sdk: MCP 协议 SDK
Puppeteer: 无头浏览器自动化
Chromium: 无头浏览器内核
undici: 高性能 HTTP 客户端（备用）
zod: 运行时类型验证

许可证

MIT License

后续计划

支持获取文档评论
支持获取用户的所有知识库
支持批量导出文档
缓存机制优化性能
支持 Token 认证（给超级会员用户）

如有问题或建议，欢迎提 Issue！

Yuque MCP Server

语雀 MCP Server

📌 环境变量快速参考

功能特性

认证方式与实现

如何获取 Cookie

方式一：仅使用 _yuque_session（推荐，简单）

方式二：使用完整 Cookie 字符串（更稳定）

安装步骤

1. 安装依赖

2. 配置环境变量

3. 构建项目

4. 完整配置示例

场景一：公有云个人用户（最简单）

场景二：企业私有部署（推荐配置）

场景三：直接在 mcp.json 中配置（无需 .env）

配置 Cursor MCP

Cursor 配置文件位置

方式一：使用 .env 文件（推荐）

方式二：直接在 mcp.json 中配置环境变量

公有云配置示例（最简单）

企业私有部署配置示例

启动服务

使用方法

示例 1: 获取文档详情

示例 2: 搜索文档

示例 3: 获取知识库目录

示例 4: 列出所有文档

MCP 工具说明

1. get-yuque-doc

2. get-yuque-toc

3. search-yuque-docs

4. list-yuque-docs

项目结构

开发命令

故障排除

1. 认证失败

2. 无法获取文档

3. Cursor 无法找到 MCP 服务

4. Cookie 过期频率

5. 企业私有部署特殊问题

6. 中文命名空间无法识别

安全建议

Cookie 安全

环境变量管理最佳实践

.gitignore 配置示例

与 Jira MCP 的对比

技术栈

许可证

相关链接

后续计划

语雀 MCP Server

📌 环境变量快速参考

功能特性

认证方式与实现

如何获取 Cookie

方式一：仅使用 _yuque_session（推荐，简单）

方式二：使用完整 Cookie 字符串（更稳定）

安装步骤

1. 安装依赖

2. 配置环境变量

3. 构建项目

4. 完整配置示例

场景一：公有云个人用户（最简单）

场景二：企业私有部署（推荐配置）

场景三：直接在 mcp.json 中配置（无需 .env）

配置 Cursor MCP

Cursor 配置文件位置

方式一：使用 .env 文件（推荐）

方式二：直接在 mcp.json 中配置环境变量

公有云配置示例（最简单）

企业私有部署配置示例

启动服务

使用方法

示例 1: 获取文档详情

示例 2: 搜索文档

示例 3: 获取知识库目录

示例 4: 列出所有文档

MCP 工具说明

1. get-yuque-doc

方式一：仅使用 `_yuque_session`（推荐，简单）

方式一：仅使用 `_yuque_session`（推荐，简单）