yuque-mcp-plus

v0.3.1

Published

a month ago

Yuque MCP server with TOC, parentUuid, move, and multipart support.

0High
0Medium
0Low

michaeljou

mcp yuque model-context-protocol docs knowledge-base

yuque-mcp-plus

语雀 MCP 服务。

它在现有 yuque-mcp-server 的基础上补了几类关键能力：

默认知识库解析
知识库 TOC/目录树查询
支持 parentUuid 的文档创建
文档与目录节点移动
目录节点创建与删除
官方命名兼容别名
通用 OpenAPI 透传 yuque_request
通用 multipart 上传透传 yuque_multipart_request

英文文档见 README.en.md。

适用场景

适合这些语雀自动化需求：

按目录结构维护知识库
在指定目录下创建文档
批量重组目录或文档位置
通过 MCP 给 AI 助手提供稳定的语雀管理能力
在官方工具未覆盖的接口上，通过通用请求继续扩展

当前状态

已经完成并验证：

yuque_get_default_repository
yuque_get_repository_toc_tree
yuque_create_doc + parentUuid
yuque_move_document
yuque_create_toc_node
yuque_delete_toc_node
根节点自动删除
官方兼容别名工具

真实联调已通过的能力：

创建根目录节点
在目录节点下创建文档
移动目录节点
删除目录节点
删除测试文档

环境变量

必填：

YUQUE_TOKEN

可选：

YUQUE_API_BASE_URL
YUQUE_TIMEOUT_MS
YUQUE_RETRIES
YUQUE_DEFAULT_REPO_ID
YUQUE_DEFAULT_REPO_NAMESPACE

说明：

YUQUE_DEFAULT_REPO_ID 优先级高于 YUQUE_DEFAULT_REPO_NAMESPACE
两者都不填时，会回退到当前账号可访问的第一个知识库

运行方式

通过 npm 直接运行：

npx yuque-mcp-plus

如果要带环境变量：

YUQUE_TOKEN="your-token" npx yuque-mcp-plus

直接启动：

node ./src/index.js

本地检查：

npm run check

本地测试：

npm test

版本变更记录：

CHANGELOG.md

发布步骤：

RELEASE.md

Codex MCP 配置示例

如果你想在本地源码和 npm 已发布包之间切换，可以直接替换 command + args。

源码模式：

[mcp_servers.yuque]
command = "node"
args = [ "/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js" ]

[mcp_servers.yuque.env]
YUQUE_TOKEN = "your-token"

npm 模式：

[mcp_servers.yuque]
command = "npx"
args = [ "-y", "yuque-mcp-plus" ]

[mcp_servers.yuque.env]
YUQUE_TOKEN = "your-token"

其他客户端接入

下面这些示例基于 2026-03-04 当天可查到的客户端文档整理。不同版本的 UI 或配置文件位置可能会变，但本地 stdio 启动方式基本一致。

Claude Code

官方文档当前推荐直接用命令注册本地 stdio MCP：

源码模式：

claude mcp add --transport stdio yuque -- node /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js

npm 模式：

claude mcp add --transport stdio yuque -- npx -y yuque-mcp-plus

如果要带环境变量：

claude mcp add --transport stdio --env YUQUE_TOKEN=your-token yuque -- node /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js
claude mcp add --transport stdio --env YUQUE_TOKEN=your-token yuque -- npx -y yuque-mcp-plus

常用管理命令：

claude mcp list
claude mcp get yuque

如果你使用项目共享配置，也可以把它写进项目根目录的 .mcp.json：

源码模式：

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": [
        "/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js"
      ],
      "env": {
        "YUQUE_TOKEN": "${YUQUE_TOKEN}"
      }
    }
  }
}

npm 模式：

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

Qoder

Qoder 当前支持在设置页里直接添加 MCP。

操作路径：

打开 Qoder Settings
进入 MCP
在 My Servers 里点击 + Add
粘贴 JSON 配置并保存

本项目可直接使用：

源码模式：

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": [
        "/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js"
      ],
      "env": {
        "YUQUE_TOKEN": "your-token"
      }
    }
  }
}

npm 模式：

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

保存后如果能看到连接图标，说明服务已成功连上。使用时要切到 Agent mode，这样 Qoder 才会调用 MCP 工具。

OpenCode

OpenCode 当前在 opencode.jsonc 里配置 MCP。本地 MCP 要放在 mcp 字段下，并声明为 type: "local"。

示例：

源码模式：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yuque": {
      "type": "local",
      "command": [
        "node",
        "/Users/program/code/code_mcp/yuque-mcp-plus/src/index.js"
      ],
      "enabled": true,
      "environment": {
        "YUQUE_TOKEN": "your-token"
      }
    }
  }
}

npm 模式：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yuque": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "yuque-mcp-plus"
      ],
      "enabled": true,
      "environment": {
        "YUQUE_TOKEN": "your-token"
      }
    }
  }
}

使用时可以在提示词里直接点名，例如：

use the yuque tool to list my repositories

Trae

Trae 已经支持 MCP，但我当前没查到和 Qoder/OpenCode 一样完整公开的本地配置文件格式文档。所以这里按目前公开的接入方式写最稳的 UI 配置步骤。

常见操作路径：

打开聊天框
点击右上角齿轮
进入 MCP
添加一个本地 STDIO 服务

建议填写：

源码模式：

Name: yuque
Command: node
Args: /Users/program/code/code_mcp/yuque-mcp-plus/src/index.js
Env: YUQUE_TOKEN=your-token

npm 模式：

Name: yuque
Command: npx
Args: -y yuque-mcp-plus
Env: YUQUE_TOKEN=your-token

说明：

Trae 的具体入口位置和字段名可能会随版本变化
如果你的版本支持 JSON 配置导入，可以直接复用 Qoder 的那份 mcpServers 配置
如果是通过界面逐项填写，本项目本质上只需要 command + args + env

工具清单

核心工具

| 工具 | 用途 | 常用关键参数 | | --- | --- | --- | | yuque_hello | 检查服务和 token 是否可用 | 无 | | yuque_request | 通用 OpenAPI 透传 | method, path, params, body | | yuque_multipart_request | 通用 multipart 上传请求，适合附件类接口 | method, path, params, fields, files | | yuque_get_user | 获取当前用户信息 | 无 | | yuque_get_repos | 获取知识库列表 | ownerLogin, ownerType, userId | | yuque_list_groups | 获取当前用户或指定用户的团队列表 | userId | | yuque_get_repo | 获取单个知识库详情 | repoId, repoNamespace | | yuque_get_default_repository | 解析默认知识库 | 无 | | yuque_search | 搜索文档或知识库内容 | query, type, repoId, page |

知识库与文档

| 工具 | 用途 | 常用关键参数 | | --- | --- | --- | | yuque_get_docs | 列出知识库文档 | repoId, repoNamespace, limit, offset | | yuque_get_doc | 获取单篇文档详情 | docId, repoId, repoNamespace | | yuque_create_doc | 创建文档，可挂到目录节点下 | repoId, title, body, format, parentUuid | | yuque_update_doc | 更新文档标题或正文 | docId, title, body, format | | yuque_delete_doc | 删除文档 | docId, repoId, repoNamespace | | yuque_create_repo | 创建知识库 | name, slug, description, ownerLogin, ownerType | | yuque_update_repo | 更新知识库配置 | repoId, repoNamespace, name, slug, description, isPublic | | yuque_delete_repo | 删除知识库 | repoId, repoNamespace |

TOC 与结构调整

| 工具 | 用途 | 常用关键参数 | | --- | --- | --- | | yuque_get_repository_toc_tree | 获取完整目录树 | repoId, repoNamespace | | yuque_create_toc_node | 创建目录或链接节点 | repoId, title, nodeType, parentUuid, actionMode, position | | yuque_delete_toc_node | 删除目录节点，支持根节点自动推导 | repoId, nodeUuid, parentUuid | | yuque_move_document | 移动文档或目录节点 | repoId, docId 或 nodeUuid, parentUuid, actionMode, position | | yuque_update_repository_toc | 直接透传底层 TOC 更新 | repoId, repoNamespace, payload |

版本、团队与统计

| 工具 | 用途 | 常用关键参数 | | --- | --- | --- | | yuque_list_doc_versions | 获取文档版本列表 | docId | | yuque_get_doc_version | 获取某个文档版本详情 | versionId | | yuque_list_group_members | 获取团队成员列表 | login | | yuque_update_group_member | 更新团队成员角色 | login, userId, role | | yuque_remove_group_member | 移除团队成员 | login, userId | | yuque_group_stats | 获取团队总统计 | login | | yuque_group_member_stats | 获取团队成员统计 | login | | yuque_group_book_stats | 获取团队知识库统计 | login | | yuque_group_doc_stats | 获取团队文档统计 | login |

兼容别名

| 别名 | 实际工具 | | --- | --- | | yuque_list_repos | yuque_get_repos | | yuque_list_docs | yuque_get_docs | | yuque_get_toc | yuque_get_repository_toc_tree | | yuque_update_toc | yuque_update_repository_toc |

常用调用示例

1. 获取默认知识库

{}

对应工具：

yuque_get_default_repository

2. 获取知识库目录树

{
  "repoId": 63978478
}

对应工具：

yuque_get_repository_toc_tree

3. 在指定目录下创建文档

{
  "repoId": 63978478,
  "title": "新文档",
  "body": "# 标题\n\n正文",
  "format": "markdown",
  "parentUuid": "-W39TNJu_tufwcVm"
}

对应工具：

yuque_create_doc

4. 创建目录节点

{
  "repoId": 63978478,
  "title": "新目录",
  "nodeType": "TITLE",
  "parentUuid": "-W39TNJu_tufwcVm",
  "actionMode": "child",
  "position": "append"
}

如果不传 parentUuid，则创建在根层级。

对应工具：

yuque_create_toc_node

5. 删除目录节点

最简单的调用方式：

{
  "repoId": 63978478,
  "nodeUuid": "CxEXaBKTPFRKaopb"
}

说明：

对子节点，服务会自动解析 parent_uuid
对根节点，服务会自动解析删除策略
你也可以手动传 parentUuid 覆盖自动推导

对应工具：

yuque_delete_toc_node

6. 移动文档或目录节点

{
  "repoId": 63978478,
  "nodeUuid": "Mir36kbfs2f4g130",
  "parentUuid": "-W39TNJu_tufwcVm",
  "actionMode": "child",
  "position": "append"
}

如果是移动文档，也可以传：

{
  "repoId": 63978478,
  "docId": 259413650,
  "parentUuid": "-W39TNJu_tufwcVm",
  "actionMode": "child",
  "position": "append"
}

对应工具：

yuque_move_document

7. 通用 OpenAPI 请求

{
  "method": "GET",
  "path": "/user"
}

或：

{
  "method": "GET",
  "path": "/search",
  "params": {
    "q": "联商客",
    "type": "doc"
  }
}

对应工具：

yuque_request

工具速查示例

下面这部分按工具拆开，适合复制后直接改参数。

`yuque_get_default_repository`

{}

`yuque_get_repos`

{}

按用户或团队过滤：

{
  "ownerLogin": "your-team",
  "ownerType": "groups"
}

`yuque_get_repo`

{
  "repoId": 63978478
}

`yuque_get_repository_toc_tree`

{
  "repoId": 63978478
}

`yuque_create_toc_node`

创建根目录：

{
  "repoId": 63978478,
  "title": "一级目录",
  "nodeType": "TITLE"
}

创建子目录：

{
  "repoId": 63978478,
  "title": "二级目录",
  "nodeType": "TITLE",
  "parentUuid": "-W39TNJu_tufwcVm",
  "actionMode": "child",
  "position": "append"
}

`yuque_delete_toc_node`

自动删除目录节点：

{
  "repoId": 63978478,
  "nodeUuid": "CxEXaBKTPFRKaopb"
}

`yuque_create_doc`

创建根层级文档：

{
  "repoId": 63978478,
  "title": "根文档",
  "body": "# 标题\n\n正文",
  "format": "markdown"
}

创建到目录下：

{
  "repoId": 63978478,
  "title": "目录文档",
  "body": "# 标题\n\n正文",
  "format": "markdown",
  "parentUuid": "-W39TNJu_tufwcVm"
}

`yuque_update_doc`

{
  "docId": 259413650,
  "title": "更新后的标题",
  "body": "# 新标题\n\n新正文",
  "format": "markdown"
}

`yuque_delete_doc`

{
  "docId": 259413650
}

`yuque_move_document`

按文档移动：

{
  "repoId": 63978478,
  "docId": 259413650,
  "parentUuid": "-W39TNJu_tufwcVm",
  "actionMode": "child",
  "position": "append"
}

按目录节点移动：

{
  "repoId": 63978478,
  "nodeUuid": "Mir36kbfs2f4g130",
  "parentUuid": "-W39TNJu_tufwcVm",
  "actionMode": "child",
  "position": "append"
}

`yuque_search`

{
  "query": "联商客",
  "type": "doc",
  "repoId": 63978478
}

`yuque_list_doc_versions`

{
  "docId": 259413650
}

`yuque_get_doc_version`

{
  "versionId": 123456789
}

`yuque_list_group_members`

{
  "login": "your-team"
}

`yuque_update_group_member`

{
  "login": "your-team",
  "userId": 123456,
  "role": 1
}

`yuque_remove_group_member`

{
  "login": "your-team",
  "userId": 123456
}

`yuque_group_stats`

{
  "login": "your-team"
}

`yuque_request`

查询当前用户：

{
  "method": "GET",
  "path": "/user"
}

评论类请求示例：

{
  "method": "POST",
  "path": "/repos/63978478/docs/259413650/comments",
  "body": {
    "body": "这是一条评论"
  }
}

`yuque_multipart_request`

附件上传类请求示例：

{
  "method": "POST",
  "path": "/repos/63978478/attachments",
  "fields": {
    "type": "file"
  },
  "files": [
    {
      "fieldName": "file",
      "filePath": "/absolute/path/to/example.png",
      "contentType": "image/png"
    }
  ]
}

底层 TOC 更新：

{
  "path": "/repos/63978478/toc",
  "method": "PUT",
  "body": {
    "action": "removeNode",
    "action_mode": "child",
    "target_uuid": "-W39TNJu_tufwcVm",
    "node_uuid": "Mir36kbfs2f4g130"
  }
}

命名兼容说明

为了兼容官方 yuque/yuque-mcp-server 的命名习惯，项目提供了这些别名：

yuque_list_repos -> yuque_get_repos
yuque_list_docs -> yuque_get_docs
yuque_get_toc -> yuque_get_repository_toc_tree
yuque_update_toc -> yuque_update_repository_toc

已知边界

评论暂未封装成专用工具，建议通过 yuque_request 访问
附件暂未封装成官方专用工具，但现在可通过 yuque_multipart_request 处理上传类接口
yuque_update_repository_toc 属于底层透传工具，适合高级场景

说明：

我已核对官方 openapi-metadata 和 sdk
其中没有明确公开 comments / attachments 的专用 OpenAPI 定义
所以当前实现选择“补强通用能力”，而不是硬编码猜测端点

真实联调记录

以下场景已经在真实语雀知识库里跑通过：

默认知识库解析

yuque_get_default_repository 可以正常返回默认知识库
返回中会带 _defaultSource
该字段用于标记默认知识库的解析来源，方便排查配置问题

目录树查询

yuque_get_repository_toc_tree 可以正确返回 TITLE、DOC 和层级关系
已验证返回字段中包含 uuid、parent_uuid、prev_uuid、sibling_uuid

在目录下创建文档

yuque_create_doc 传入 parentUuid 后，可以先创建文档，再正确挂载到指定目录下
已验证创建出的文档在 TOC 中可见，且 parent_uuid 正确

文档移动

yuque_move_document 已验证支持：
通过 docId 移动文档
通过 nodeUuid 移动 TOC 节点
可在根层级与目录层级之间移动

创建目录节点

yuque_create_toc_node 已验证可创建根层级 TITLE
也已验证可创建子级目录节点

删除目录节点

yuque_delete_toc_node 已验证可删除：
有父目录的普通目录节点
根层级目录节点
对根节点删除时，服务会自动推导正确的删除策略

清理测试数据

测试过程中创建的临时文档和临时目录节点都已成功删除
当前实现已经适合做日常知识库结构维护

常见报错处理

`Missing YUQUE_TOKEN`

原因：

没有注入 YUQUE_TOKEN
终端手动运行时忘记带环境变量

处理：

检查 config.toml 里的 [mcp_servers.yuque.env]
或者在终端启动时显式传入：

YUQUE_TOKEN="your-token" node ./src/index.js

`doc not found`

原因：

文档 ID 不存在
文档已经被删除
仓库不匹配

处理：

先用 yuque_get_docs 或 yuque_get_doc 确认 docId
确认 repoId 或 repoNamespace 正确

`action invalid`

原因：

传给 yuque_update_repository_toc 的底层 action 不符合语雀实际支持的值

处理：

优先使用上层工具：
yuque_create_toc_node
yuque_delete_toc_node
yuque_move_document
只有在高级场景下再使用 yuque_update_repository_toc

`missing action_mode`

原因：

调用 TOC 更新接口时缺少 action_mode

处理：

尽量不要手写 TOC 底层 payload
对删除目录节点，优先使用 yuque_delete_toc_node

`action_mode invalid`

原因：

action_mode 与当前操作不匹配

处理：

删除子节点通常对应 child
删除根层级节点通常需要通过相邻节点推导 sibling
该逻辑已经封装在 yuque_delete_toc_node 中

`getaddrinfo ENOTFOUND www.yuque.com`

原因：

当前运行环境没有网络
被沙箱或代理限制

处理：

在允许联网的环境执行真实联调
在 Codex 中如遇沙箱网络限制，需要提权后重跑

工具新增后当前会话里看不到

原因：

MCP 配置已更新，但当前会话工具面没有热刷新

处理：

重启 Codex
重启后重新进入会话，再次调用新工具

项目结构

src/
  config.js
  index.js
  server.js
  tools.js
  yuque-client.js

tests/
  tools.test.js
  yuque-client.test.js

开发说明

核心实现位置：

配置读取：src/config.js
MCP 服务入口：src/server.js
工具定义与分发：src/tools.js
语雀 API 客户端：src/yuque-client.js

测试文件：

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

yuque-mcp-plus

适用场景

当前状态

环境变量

运行方式

Codex MCP 配置示例

其他客户端接入

Claude Code

Qoder

OpenCode

Trae

工具清单

核心工具

知识库与文档

TOC 与结构调整

版本、团队与统计

兼容别名

常用调用示例

1. 获取默认知识库

2. 获取知识库目录树

3. 在指定目录下创建文档

4. 创建目录节点

5. 删除目录节点

6. 移动文档或目录节点

7. 通用 OpenAPI 请求

工具速查示例

yuque_get_default_repository

yuque_get_repos

yuque_get_repo

yuque_get_repository_toc_tree

yuque_create_toc_node

yuque_delete_toc_node

yuque_create_doc

yuque_update_doc

yuque_delete_doc

yuque_move_document

yuque_search

yuque_list_doc_versions

yuque_get_doc_version

yuque_list_group_members

yuque_update_group_member

yuque_remove_group_member

yuque_group_stats

yuque_request

yuque_multipart_request

命名兼容说明

已知边界

真实联调记录

默认知识库解析

目录树查询

在目录下创建文档

文档移动

创建目录节点

删除目录节点

清理测试数据

常见报错处理

Missing YUQUE_TOKEN

doc not found

action invalid

missing action_mode

action_mode invalid

getaddrinfo ENOTFOUND www.yuque.com

工具新增后当前会话里看不到

项目结构

开发说明

`yuque_get_default_repository`

`yuque_get_repos`

`yuque_get_repo`

`yuque_get_repository_toc_tree`

`yuque_create_toc_node`

`yuque_delete_toc_node`

`yuque_create_doc`

`yuque_update_doc`

`yuque_delete_doc`

`yuque_move_document`

`yuque_search`

`yuque_list_doc_versions`

`yuque_get_doc_version`

`yuque_list_group_members`

`yuque_update_group_member`

`yuque_remove_group_member`

`yuque_group_stats`

`yuque_request`

`yuque_multipart_request`

`Missing YUQUE_TOKEN`

`doc not found`

`action invalid`

`missing action_mode`

`action_mode invalid`

`getaddrinfo ENOTFOUND www.yuque.com`