yuque-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@yuque-mcp list documents in my personal knowledge base"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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)Related MCP server: Yuque MCP Server
特性
基于语雀 OpenAPI 2.0.1 规范实现
三级权限控制,默认只读,防止 AI 误操作
支持 stdio 传输模式,兼容主流 MCP 客户端
支持 Docker 部署
权限级别
级别 | 说明 | 可用操作 | 工具数 |
| 只读 | GET 请求 | 14 |
| 读写 | GET + POST/PUT/PATCH | 22 |
| 管理 | 所有操作包括 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改为对应的地址即可。
可用工具
只读工具(所有权限级别)
工具名 | 说明 |
| 心跳检测 |
| 获取当前用户详情 |
| 获取用户团队列表 |
| 获取用户知识库列表 |
| 获取团队知识库列表 |
| 获取知识库详情 |
| 获取文档列表 |
| 获取文档详情 |
| 通过知识库 ID 获取文档 |
| 获取知识库目录 |
| 通过知识库 ID 获取目录 |
| 获取文档历史版本列表 |
| 获取文档历史版本详情 |
| 通用搜索 |
写入工具(write/admin 权限)
工具名 | 说明 |
| 创建知识库 |
| 更新知识库 |
| 创建文档 |
| 更新文档 |
| 通过知识库 ID 创建文档 |
| 通过知识库 ID 更新文档 |
| 更新知识库目录 |
| 通过知识库 ID 更新目录 |
删除工具(仅 admin 权限)
工具名 | 说明 |
| 删除知识库 |
| 删除文档 |
| 通过知识库 ID 删除文档 |
环境变量
在 MCP 客户端配置的 env 字段中设置:
变量名 | 必需 | 默认值 | 说明 |
| 是 | - | 语雀 API Token |
| 否 |
| 权限级别(read/write/admin) |
| 否 |
| 语雀 API 地址,私有域名时需修改 |
| 否 | - | 设为 |
获取语雀 Token
登录 语雀
进入 个人设置 → Token
创建一个新的 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
Available Tools
14 toolsyuque_get_docB
获取文档详情
权限要求: read 参数:
group_login: 团队/用户 login
book_slug: 知识库 slug
id: 文档 ID
page_size: 评论每页数量 (可选)
page: 评论页码 (可选)
Inputs: group_login (required), book_slug (required), id (required), page_size, +1 more. Returns: result
yuque_get_doc_by_book_idA
通过知识库 ID 获取文档详情
权限要求: read 参数:
book_id: 知识库 ID
id: 文档 ID
page_size: 评论每页数量 (可选)
page: 评论页码 (可选)
Inputs: book_id (required), id (required), page_size, page. Returns: result
yuque_get_docsA
获取知识库的文档列表
权限要求: read 参数:
group_login: 团队/用户 login
book_slug: 知识库 slug
offset: 偏移量 (可选)
limit: 每页数量 (可选)
optional_properties: 附加属性 (可选, 如 body, body_html)
Inputs: group_login (required), book_slug (required), offset, limit, +1 more. Returns: result
yuque_get_doc_versionB
获取文档历史版本详情
权限要求: read 参数:
id: 版本 ID
Inputs: id (required). Returns: result
yuque_get_doc_versionsA
获取文档历史版本列表
权限要求: read 参数:
doc_id: 文档 ID
Inputs: doc_id (required). Returns: result
yuque_get_group_reposA
获取指定团队的知识库列表
权限要求: read 参数:
login: 团队 login
offset: 偏移量 (可选)
limit: 每页数量 (可选)
type: 知识库类型 (可选)
Inputs: login (required), offset, limit, type. Returns: result
yuque_get_repoA
获取知识库详情
权限要求: read 参数:
group_login: 团队/用户 login
book_slug: 知识库 slug
Inputs: group_login (required), book_slug (required). Returns: result
yuque_get_tocB
获取知识库目录
权限要求: read 参数:
group_login: 团队/用户 login
book_slug: 知识库 slug
Inputs: group_login (required), book_slug (required). Returns: result
yuque_get_toc_by_book_idC
通过知识库 ID 获取目录
权限要求: read 参数:
book_id: 知识库 ID
Inputs: book_id (required). Returns: result
yuque_get_user_groupsB
获取指定用户所属的团队列表
权限要求: read 参数:
id: 用户 ID 或 login
role: 角色过滤 (可选)
offset: 偏移量 (可选)
Inputs: id (required), role, offset. Returns: result
yuque_get_user_infoA
获取当前 Token 对应的用户详情
权限要求: read 返回: 用户信息,包含 id、login、name、avatar_url 等
Inputs: no named parameters. Returns: result
yuque_get_user_reposA
获取指定用户的知识库列表
权限要求: read 参数:
login: 用户 login
offset: 偏移量 (可选)
limit: 每页数量 (可选)
type: 知识库类型 (可选, 如 Book/Design/System)
Inputs: login (required), offset, limit, type. Returns: result
yuque_helloA
心跳检测 - 测试与语雀 API 的连接是否正常
权限要求: read
Inputs: no named parameters. Returns: result
yuque_searchA
在语雀中进行通用搜索
权限要求: read 参数:
q: 搜索关键词
type: 搜索类型 (可选, 如 doc/repo/user)
scope: 搜索范围 (可选)
page: 页码 (可选)
offset: 偏移量 (可选)
Inputs: q (required), type, scope, page, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have distinct purposes, but there is some redundancy between `yuque_get_doc` and `yuque_get_doc_by_book_id` (and similarly for TOC). However, the descriptions clearly differentiate them by the way the book is specified.
All tools follow a consistent `yuque_<verb>_<noun>` pattern, with variants like `_by_book_id` for clarity. No mixing of styles or inconsistent verbs.
14 tools cover the main read operations for a knowledge base platform: document retrieval, version history, repositories, TOC, user info, groups, search, and heartbeat. The scope is well-balanced.
All tools are read-only; there are no create, update, or delete operations. For a comprehensive Yuque interaction, this is a major gap. The server appears to intentionally limit to read, but it lacks essential write capabilities.
Maintenance
Related MCP Connectors
Securely search and manage workspace context files for AI agents and teams.
Shared, permission-aware company context for AI agents, with provenance, approvals and audit.
Knowledge base MCP for AI agents on iknow.dev. Search, read, and maintain via OAuth.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model-Context-Protocol server that integrates with Yuque (语雀) knowledge base platform, allowing AI models to create, read, update, and delete documents, search content, and retrieve analytics data through defined tools.1469ISC
- AlicenseBqualityDmaintenanceEnables interaction with Yuque (语雀) knowledge base platform through their API. Supports document management, search, and repository operations including creating, reading, updating, and deleting documents in multiple formats.93MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Yuque (语雀) platform through MCP protocol, supporting knowledge base management, document operations, search, and team collaboration features.11MIT

Yuque MCP Serverofficial
AlicenseBqualityDmaintenanceMCP server for Yuque (语雀) that exposes your knowledge base to AI assistants through the Model Context Protocol.19731 npm267MIT