Yuque MCP Server

MCP文档知识

提供方 saoqixiaomm

文档知识 未标注 Token 社区 / 第三方 Cursor

一个用于在Cursor中通过语雀URL或知识库命名空间获取文档信息的MCP服务器,支持文档搜索、目录结构获取等功能。

一句话选型结论

按资料字段整理

Yuque MCP Server 属于文档知识类 MCP 服务器,传输方式未标注,Token,可直接接入 Cursor,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式未标注 鉴权Token 部署方式本地部署
GitHub 星标 3 仓库热度,无公开仓库时显示未标注
工具数 4 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量4暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

文档管理TypeScript本地部署知识库无头浏览器Cookie认证MCP协议

安装与配置

未标注 Token
上游未给出传输方式
  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 4 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 4 个工具,职责相对集中,接入后不容易误操作。
  • 已适配 Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Yuque MCP Server当前 4 未标注 本地部署 无 2026-05-17
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方saoqixiaomm上游标注的维护方 saoqixiaomm
分类文档知识本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

15.3 KB
来自项目仓库与上游目录的原文,未做删改

语雀 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,支持中文)

快速配置示例:```bash

.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 权限限制
- ✅ 无需语雀超级会员

### 如何获取 Cookie

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

#### 方式一:仅使用 `_yuque_session`(推荐,简单)

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

#### 方式二:使用完整 Cookie 字符串(更稳定)

1. 登录语雀网站后,打开浏览器开发者工具(F12)
2. 切换到 **Network**(网络)标签
3. 刷新页面或访问任意语雀文档
4. 点击任意请求,找到 **Request Headers**(请求头)
5. 找到 `Cookie:` 字段,复制完整的 Cookie 字符串

**完整 Cookie 示例格式**:```
lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx; current_theme=default; acw_tc=xxx

> ⚠️ 注意:
> - Cookie 会过期(通常几天到几周),过期后需要重新获取
> - 使用完整 Cookie 字符串通常更稳定,但包含更多敏感信息,请妥善保管

安装步骤

1. 安装依赖```bash

cd yuque-mcp
npm install


### 2. 配置环境变量

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

然后编辑 .env 文件,填入你的配置:```bash

语雀 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`,支持中文 | `张三/我的知识库` |

**配置建议**:

1. **公有云用户**:只需配置 `YUQUE_COOKIE`
2. **企业用户**:需要同时配置 `YUQUE_COOKIE` 和 `YUQUE_BASE_URL`
3. **常用知识库**:建议配置 `YUQUE_NAMESPACE`,简化后续操作

### 3. 构建项目```bash
npm run build

4. 完整配置示例

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

场景一:公有云个人用户(最简单)

.env 文件:```bash
YUQUE_COOKIE=n_FzpQWqYiQEgGAKM6Y9BYtxBrmoJD16z6Jfv4wlFVvUy3_O621jF6Gg9_6R59pueqqvebZW7EC6tqPoU6qD9A==


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

场景二:企业私有部署(推荐配置)

.env 文件:```bash

企业语雀地址

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 文件**:```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"]
}
}
}

场景三:直接在 mcp.json 中配置(无需 .env)```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",
"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`:```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": [
"/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
]
}
}
}

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

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

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

公有云配置示例(最简单)```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"
}
}
}
}


#### 企业私有部署配置示例```json
{
"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"
}
}
}
}

注意事项:

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

启动服务

  1. 保存配置文件
  2. 重启 Cursor 使配置生效
  3. 在 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

**支持的调用方式**:```typescript
// 方式 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 文件

## 开发命令```bash
# 安装依赖
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 日志,确认服务是否启动成功

4. Cookie 过期频率

Cookie 的有效期取决于语雀的设置,通常:

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

建议:

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

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

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

解决方法:

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

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

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

解决方法:

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

安全建议

⚠️ 重要提示:

Cookie 安全

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

环境变量管理最佳实践

  1. 使用 .env 文件(推荐)```bash

在项目根目录创建 .env 文件

添加到 .gitignore 防止提交

echo ".env" >> .gitignore


2. **在 mcp.json 中配置**
- mcp.json 通常在用户目录下(`~/.cursor/mcp.json`),不会被 git 追踪
- 但要注意备份时不要泄露

3. **企业用户额外注意**
- 企业语雀可能有更严格的安全策略
- 定期检查会话状态
- 考虑使用只读权限的账号

### .gitignore 配置示例

如果你的项目使用 git,确保添加以下内容到 `.gitignore`:```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

相关链接

  • Model Context Protocol
  • 语雀开放平台
  • Cursor 官网

后续计划

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

如有问题或建议,欢迎提 Issue!

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Yuque MCP Server 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Yuque MCP Server 怎么在 Cursor 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Yuque MCP Server 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Yuque MCP Server 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Yuque MCP Server 支持哪些客户端?

资料标注支持 Cursor;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Yuque MCP Server 能提供哪些能力?

资料显示约 4 个工具;能力标签包括 文档处理、TypeScript、Cursor、知识管理。具体工具清单以官方文档为准。

Yuque MCP Server 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Yuque MCP Server 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。