语雀 MCP Server

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

📌 环境变量快速参考

快速配置示例：

# .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. 安装依赖

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 模板文件，包含详细的配置说明

环境变量详细说明:

配置建议：

1. 公有云用户：只需配置 YUQUE_COOKIE
2. 企业用户：需要同时配置 YUQUE_COOKIE 和 YUQUE_BASE_URL
3. 常用知识库：建议配置 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"
      }
    }
  }
}

注意事项：

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

支持的调用方式:

// 方式 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 日志，确认服务是否启动成功

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 文件（推荐）

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

2. 在 mcp.json 中配置

   • mcp.json 通常在用户目录下（~/.cursor/mcp.json），不会被 git 追踪
   • 但要注意备份时不要泄露

3. 企业用户额外注意

   • 企业语雀可能有更严格的安全策略
   • 定期检查会话状态
   • 考虑使用只读权限的账号

.gitignore 配置示例

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

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

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

与 Jira MCP 的对比

技术栈

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

许可证

MIT License

相关链接

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

后续计划

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

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