yuque-mcp

@saoqixiaomm/yuque-mcp

0 Stars 17 次浏览 saoqixiaomm 更新于 2026-08-23

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

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

服务介绍

语雀 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

查看源码项目主页

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

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 服务

开源版 与 企业版

企业版（含 FDE 交付）

技能定制开发服务

方式一仅使用 `_yuque_session`推荐简单

开源版与企业版