Yuque MCP Server

# 语雀 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](https://modelcontextprotocol.io/) - [语雀开放平台](https://www.yuque.com/yuque/developer/api) - [Cursor 官网](https://cursor.sh/) ## 后续计划 - [ ] 支持获取文档评论 - [ ] 支持获取用户的所有知识库 - [ ] 支持批量导出文档 - [ ] 缓存机制优化性能 - [ ] 支持 Token 认证（给超级会员用户） --- 如有问题或建议，欢迎提 Issue！