@chaoyum/yuque-mcp-server

语雀 MCP Server —— 在 Cursor 中管理语雀文档。支持下载、上传、更新、子文档创建、目录定位、知识库搜索等。兼容团队版语雀（如 bd-tech.yuque.com）和个人版，同时支持 Cookie 和 Token 认证。

功能

| 工具名 | 说明 | |--------|------| | download_yuque_doc | 输入语雀文档链接，导出为 Markdown 并保存到当前工作区的 yuque-downloads/ 目录 | | upload_to_yuque | 上传或更新语雀文档，支持三种模式：创建新文档、更新已有文档、创建子文档。可指定目录分组位置 | | list_yuque_repos | 列出/搜索当前用户的所有知识库，按名称模糊匹配 | | list_yuque_toc | 查看知识库的目录结构（树形展示分组、文档、子文档层级） | | update_yuque_config | 更新语雀配置（域名、Cookie、Token），即时生效无需重启 | | check_yuque_connection | 检测语雀连接状态和认证是否有效 |

前置条件

• Node.js >= 18
• 语雀账号（个人版或团队版均可）

认证方式

支持 Cookie 和 Token 两种认证，都跟域名绑定，不同域名的凭据不能混用。

| 方式 | 适用场景 | 获取方法 | |------|---------|---------| | Cookie（推荐） | 所有用户，免费 | 浏览器登录语雀 → F12 → Network → 任意请求 → Headers → Cookie 值全部复制 | | Token | 语雀超级会员 | 语雀 → 设置 → Token → 新建 |

安装与配置

方式一：通过 npx 直接使用（推荐）

编辑 ~/.cursor/mcp.json，添加：

{
  "mcpServers": {
    "yuque-mcp": {
      "command": "npx",
      "args": ["-y", "@chaoyum/yuque-mcp-server@latest"],
      "env": {
        "YUQUE_HOST": "https://bd-tech.yuque.com",
        "YUQUE_TOKEN": "",
        "YUQUE_COOKIE": "",
        "YUQUE_COOKIE_FILE": ""
      }
    }
  }
}

方式二：本地开发调试

git clone <repo-url>
cd yuque-mcp-server
npm install
npm run build

然后在 mcp.json 中配置：

{
  "mcpServers": {
    "yuque-mcp": {
      "command": "node",
      "args": ["你的绝对路径/yuque-mcp-server/dist/index.js"],
      "env": {
        "YUQUE_HOST": "https://bd-tech.yuque.com",
        "YUQUE_TOKEN": "",
        "YUQUE_COOKIE": "",
        "YUQUE_COOKIE_FILE": ""
      }
    }
  }
}

环境变量说明

| 变量名 | 必填 | 说明 | |--------|------|------| | YUQUE_HOST | 推荐 | 语雀域名，如 https://bd-tech.yuque.com。也可通过 update_yuque_config 或 config.json 配置 | | YUQUE_TOKEN | 可选 | 语雀个人访问令牌（需超级会员）。跟域名绑定 | | YUQUE_COOKIE | 可选 | 语雀登录 Cookie 字符串。跟域名绑定 | | YUQUE_COOKIE_FILE | 可选 | 自定义 Cookie 文件路径，默认 ~/.yuque-mcp/config.json |

以上环境变量都可以留空。 推荐使用本地配置文件管理凭据（即时生效，无需重启 Cursor）。

本地配置文件

位置：~/.yuque-mcp/config.json

{
  "host": "https://bd-tech.yuque.com",
  "cookie": "你的Cookie...",
  "token": ""
}

三个字段都可选，填了哪个用哪个。可通过 update_yuque_config 工具自动管理，也可手动编辑。

配置优先级

| 配置项 | 优先级（高 → 低） | |--------|------------------| | 域名 | 工具参数 > env YUQUE_HOST > config.json host | | 认证 | env YUQUE_TOKEN > env YUQUE_COOKIE > config.json token > config.json cookie |

环境变量修改需重启 Cursor；config.json 修改即时生效。

使用示例

下载文档

下载这个语雀文档 https://bd-tech.yuque.com/group/book/slug

自动保存到工作区下的 yuque-downloads/ 目录。也可指定路径：

下载到 D:\docs 目录 https://bd-tech.yuque.com/group/book/slug

上传（创建新文档）

把 @xxx.md 上传到 https://bd-tech.yuque.com/group/book

在指定目录分组下创建

把 @xxx.md 上传到 https://bd-tech.yuque.com/group/book ，放在「互联互通」目录下

创建子文档

把 @xxx.md 作为子文档上传到 https://bd-tech.yuque.com/group/book/parent-slug

更新已有文档

用 @xxx.md 更新这个语雀文档 https://bd-tech.yuque.com/group/book/slug

搜索知识库

列出我的语雀知识库

搜索包含"充电"的知识库

查看目录结构

看一下 https://bd-tech.yuque.com/group/book 的目录结构

更新配置

更新语雀配置，Cookie 是：lang=zh-cn; _yuque_session=xxx...

检查连接

检查一下语雀连接是否正常

项目结构

yuque-mcp-server/
├── package.json
├── tsconfig.json
├── README.md
├── .npmrc
├── src/
│   ├── index.ts          # MCP Server 入口 + 工具注册
│   ├── yuque-client.ts   # 语雀 API 封装、认证、配置管理
│   └── utils.ts          # 文件操作、Markdown 清洗
└── dist/                 # 编译产物

License

MIT