yuque-mcp

Name: yuque-mcp
Author: yuque

本地服务

github.com/yuque记忆与知识25915 周前更新

代码仓库

关于 yuque-mcp

yuque-mcp 是语雀的 MCP 服务，让 AI 助手读取和写入用户的语雀知识库。它面向使用语雀管理文档的个人与团队，支持个人令牌与空间绑定的团队令牌。

主要功能

01检索文档与仓库
02管理知识库、文档与目录
03读写笔记（小记）
04读取与编辑画板（脑图、流程图）
05一条命令写入各客户端配置

适用场景

01检索语雀内容并生成摘要
02将会议记录整理为知识库文档
03为设计文档添加流程图

MCP 相关

该项目是一个 MCP 服务，向 MCP 客户端暴露 19 个语雀 API 工具，覆盖用户、知识库、文档、目录、笔记和画板的读写操作。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "yuque-yuque": {
      "command": "npx",
      "args": [
        "-y",
        "yuque-mcp"
      ],
      "env": {
        "YUQUE_PERSONAL_TOKEN": "<YUQUE_PERSONAL_TOKEN>",
        "YUQUE_GROUP_TOKEN": "<YUQUE_GROUP_TOKEN>",
        "YUQUE_TOKEN": "<YUQUE_TOKEN>"
      }
    }
  }
}

启动命令npx -y yuque-mcp

需要配置的环境变量

YUQUE_PERSONAL_TOKEN密钥Yuque personal API token (get from https://www.yuque.com/settings/tokens). Use one of: YUQUE_PERSONAL_TOKEN, YUQUE_GROUP_TOKEN, or YUQUE_TOKEN.

YUQUE_GROUP_TOKEN密钥Yuque group/team API token (alternative to YUQUE_PERSONAL_TOKEN for team workspaces).

YUQUE_TOKEN密钥Yuque API token (legacy, use YUQUE_PERSONAL_TOKEN or YUQUE_GROUP_TOKEN instead).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmyuque-mcp0.1.4stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Yuque MCP 服务

让 AI 助手通过 Model Context Protocol 阅读和编写你的 Yuque（语雀）知识库。

快速开始 · 工具 · 故障排查 · 文档 · 中文文档

连接后，你可以向助手提出这样的问题：

“在我的 Yuque 中搜索所有关于金丝雀发布的内容，并整理成一页摘要。”

“把今天的会议笔记整理成一份文档，放到我的 技术研究 知识库中。”

“将此部署流水线的流程图添加到设计文档中。”

快速开始

1. 获取令牌 — 在 Yuque 开发者设置中创建令牌。如果你使用绑定到 Yuque 空间的团队令牌，也请记下空间主机地址（例如 https://your-space.yuque.com）——你需要将其作为 --host 传入。

2. 安装 — 运行一条命令即可为你的操作系统找到正确的配置文件，并在其中合并 yuque 配置项，不会修改其他服务：

npx yuque-mcp install --token=YOUR_TOKEN --client=cursor

支持的客户端：claude-desktop · vscode · cursor · windsurf · cline · trae · qoder · opencode。想使用交互式流程？运行 npx yuque-mcp setup。

Claude Code

直接注册服务：

claude mcp add yuque -- npx -y yuque-mcp --token=YOUR_TOKEN

其他 MCP 客户端（通用配置）

任何支持 stdio 传输的客户端都可以使用 — 各客户端的配置路径请参阅 docs/clients.md。

{
  "mcpServers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "yuque-mcp"],
      "env": { "YUQUE_TOKEN": "YOUR_TOKEN" }
    }
  }
}

3. 重启客户端，然后开始提问。

配置

设置	环境变量 / CLI 标志	说明
令牌（必填）	`YUQUE_TOKEN` / `--token`	个人或团队 Yuque API 令牌
主机（可选）	`YUQUE_HOST` / `--host`	站点或空间主机地址，例如 `https://your-space.yuque.com` — 绑定到空间的团队令牌和私有部署必须设置

站点根地址会规范化为 /api/v2；未设置时，主机默认值为 https://www.yuque.com/api/v2。

# Team token / private deployment
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor --host=https://your-space.yuque.com

从旧配置迁移？

YUQUE_PERSONAL_TOKEN、YUQUE_BASE_URL 和 --base-url 仍可作为旧版备用选项使用。优先级：YUQUE_TOKEN > YUQUE_PERSONAL_TOKEN > --token，以及 YUQUE_HOST > --host > YUQUE_BASE_URL > --base-url。新配置应使用 YUQUE_TOKEN 和 YUQUE_HOST。

## 工具（19）

每个工具都恰好对应一个 Yuque API 路由。

分类	工具	描述
用户	`yuque_get_user`	获取当前令牌对应的已认证用户
搜索	`yuque_search`	搜索文档或知识库，并支持分页
知识库	`yuque_list_books`	列出用户的知识库（知识库）
	`yuque_get_book`	根据 ID 或命名空间获取知识库
	`yuque_create_book`	创建知识库
	`yuque_update_book`	更新名称、别名、描述或可见性
文档	`yuque_list_docs`	列出知识库中的文档，并支持分页
	`yuque_get_doc`	获取完整内容 — markdown、`lake` 或 `html`
	`yuque_create_doc`	在知识库中创建文档
	`yuque_update_doc`	更新文档正文或元数据
目录	`yuque_get_toc`	获取知识库的目录
	`yuque_update_toc`	添加或移动单个目录节点
笔记	`yuque_list_notes`	列出笔记（小记），并支持分页和状态筛选
	`yuque_get_note`	获取笔记及其完整内容
	`yuque_create_note`	创建笔记
	`yuque_update_note`	更新笔记
画板	`yuque_get_resource`	从文档中读取画板（思维导图 / 流程图 / 图表）
	`yuque_create_resource`	在文档中创建画板
	`yuque_update_resource`	更新文档中的画板

特别是，yuque_update_doc 不能在一次调用中同时更新 markdown 正文和 title / slug / public；请分别更新元数据。完整的接口约定（包括 YMD markdown API 与旧版文档 API 之间的格式路由）请参阅 docs/capability-scope.md。

**暂未涵盖：**评论、附件上传和文件管理、权限和成员管理、文档章节级编辑，以及画板以外的结构化资源。

写入权限

创建/更新工具会修改知识库中的实际内容，且服务可以执行令牌权限范围内的任何操作。请妥善保管令牌；如果只在一个空间内工作，建议使用限定空间的团队令牌（搭配 YUQUE_HOST）。如需报告漏洞，请参阅 SECURITY.md。

故障排除

错误	解决方案
`YUQUE_TOKEN ... is required`	设置 `YUQUE_TOKEN=YOUR_TOKEN` 或传入 `--token=YOUR_TOKEN`
`401 Unauthorized`	令牌无效或已过期 — 重新生成令牌
`429 Rate Limited`	请求过多 — 请稍等片刻后重试
`410 Gone`	目标已永久删除或端点已弃用 — 请检查文档/知识库是否存在
未找到工具	更新到最新版本：`npx -y yuque-mcp@latest`
找不到 `npx` 命令	安装 Node.js v18 或更高版本

开发

git clone https://github.com/yuque/yuque-mcp-server.git
cd yuque-mcp-server
npm install
npm test              # run tests
npm run build         # compile TypeScript
npm run dev           # dev mode with hot reload

架构、技术栈和完整的工具契约位于 docs/。欢迎贡献——请参阅 CONTRIBUTING.md。