yuque-mcp

语雀 MCP 服务 - 基于语雀 OpenAPI 的 Model Context Protocol 服务，让 AI Agent（如 Qoder、Claude Desktop、Cursor 等）能够安全地访问和操作语雀知识库。

本服务是给 AI Agent 使用的 MCP 工具服务，不是手动运行的程序。安装后，AI Agent 会根据 MCP 配置自动启动本服务，通过 stdin/stdout 与之通信。你不需要手动运行它。

工作原理

AI Agent (Qoder / Claude Desktop / Cursor ...)
   │
   │  读取 MCP 配置，自动启动: yuque-mcp --permission read
   │  设置环境变量: YUQUE_TOKEN=xxx
   │
   ▼ 通过 stdin/stdout (JSON-RPC) 通信
yuque-mcp 进程
   │
   │  调用语雀 API
   ▼
语雀 API (https://www.yuque.com)

特性

• 基于语雀 OpenAPI 2.0.1 规范实现
• 三级权限控制，默认只读，防止 AI 误操作
• 支持 stdio 传输模式，兼容主流 MCP 客户端
• 支持 Docker 部署

权限级别

级别	说明	可用操作	工具数
read (默认)	只读	GET 请求	14
write	读写	GET + POST/PUT/PATCH	22
admin	管理	所有操作包括 DELETE	25

快速开始

两种方式任选其一，都只需操作一次，之后 Agent 每次调用时自动拉起服务，无需手动启动。

方式一：本地安装（推荐，简单）

# 在项目目录下安装
pip install -e .

# 验证安装成功
yuque-mcp --version

安装后 yuque-mcp 命令注册到 PATH 中，Agent 自动找到并调用。

方式二：Docker（适合不想装 Python 的用户）

# 构建镜像（只需一次，镜像会留在本机）
docker build -t yuque-mcp .

构建后镜像 yuque-mcp:latest 永久存在本地。只有修改源码才需重新构建。

配置 MCP 客户端

在 AI Agent 的 MCP 配置中添加语雀服务，填入你的 Token 和权限级别即可。

你不需要手动运行服务，Agent 会根据配置自动启动它。

本地安装方式

所有 MCP 客户端（Claude Desktop、Cursor、Qoder 等）配置相同：

{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "args": ["--permission", "read"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com"
      }
    }
  }
}

Docker 方式

{
  "mcpServers": {
    "yuque": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "YUQUE_TOKEN", "-e", "YUQUE_BASE_URL", "yuque-mcp"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com"
      }
    }
  }
}

-i 保持 stdin 开放用于 MCP 通信，--rm 用完后自动清理容器。读写模式在 args 末尾加 "--permission", "write" 即可。

如果你的语雀团队使用了私有域名（如 jojoread.yuque.com），将 YUQUE_BASE_URL 改为对应的地址即可。

可用工具

只读工具（所有权限级别）

工具名	说明
yuque_hello	心跳检测
yuque_get_user_info	获取当前用户详情
yuque_get_user_groups	获取用户团队列表
yuque_get_user_repos	获取用户知识库列表
yuque_get_group_repos	获取团队知识库列表
yuque_get_repo	获取知识库详情
yuque_get_docs	获取文档列表
yuque_get_doc	获取文档详情
yuque_get_doc_by_book_id	通过知识库 ID 获取文档
yuque_get_toc	获取知识库目录
yuque_get_toc_by_book_id	通过知识库 ID 获取目录
yuque_get_doc_versions	获取文档历史版本列表
yuque_get_doc_version	获取文档历史版本详情
yuque_search	通用搜索

写入工具（write/admin 权限）

工具名	说明
yuque_create_repo	创建知识库
yuque_update_repo	更新知识库
yuque_create_doc	创建文档
yuque_update_doc	更新文档
yuque_create_doc_by_book_id	通过知识库 ID 创建文档
yuque_update_doc_by_book_id	通过知识库 ID 更新文档
yuque_update_toc	更新知识库目录
yuque_update_toc_by_book_id	通过知识库 ID 更新目录

删除工具（仅 admin 权限）

工具名	说明
yuque_delete_repo	删除知识库
yuque_delete_doc	删除文档
yuque_delete_doc_by_book_id	通过知识库 ID 删除文档

环境变量

在 MCP 客户端配置的 env 字段中设置：

变量名	必需	默认值	说明
YUQUE_TOKEN	是	-	语雀 API Token
YUQUE_PERMISSION_LEVEL	否	read	权限级别（read/write/admin）
YUQUE_BASE_URL	否	https://www.yuque.com	语雀 API 地址，私有域名时需修改
YUQUE_MCP_DEBUG	否	-	设为 1 开启 DEBUG 日志

获取语雀 Token

1. 登录 语雀
2. 进入 个人设置 → Token
3. 创建一个新的 Token

调试

服务运行时日志输出到 stderr（MCP 协议使用 stdout），包含配置加载、API 请求/响应等信息。

开启 DEBUG 日志

在 MCP 客户端配置中添加 YUQUE_MCP_DEBUG 环境变量：

{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "args": ["--permission", "read"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com",
        "YUQUE_MCP_DEBUG": "1"
      }
    }
  }
}

日志示例

2026-06-10 15:28:33 [INFO] yuque_mcp: 配置初始化: base_url=https://www.yuque.com, token=qTGP3rqp..., permission=read, kwargs=[]
2026-06-10 15:28:33 [INFO] yuque_mcp: 创建 HTTP 客户端: base_url=https://www.yuque.com, token=qTGP3rqp...
2026-06-10 15:28:33 [INFO] yuque_mcp: API 请求: GET /api/v2/hello
2026-06-10 15:28:33 [INFO] yuque_mcp: API 响应: GET /api/v2/hello -> 200

常见问题

401 Unauthorized

如果日志显示 Token: (空)，说明 YUQUE_TOKEN 环境变量未正确传入：

• 确认 Token 写在 MCP 客户端配置的 env 字段中
• 确认环境变量名是 YUQUE_TOKEN（不是 YUQUE_YUQUE_TOKEN）
• 重启 MCP 客户端使配置生效

私有域名访问

如果你的语雀使用私有域名（如 xxx.yuque.com），需要设置 YUQUE_BASE_URL：

"YUQUE_BASE_URL": "https://xxx.yuque.com"

开发

# 安装开发依赖
pip install -e ".[dev]"

# 代码检查
ruff check src/

# 格式化
ruff format src/

License

Apache-2.0