yuque-ai-mcp
<p align="center">
<img src="https://raw.githubusercontent.com/yehuoshun/yuque-ai-mcp/main/assets/banner.png" width="800" alt="yuque-ai-mcp" />
</p>
<h1 align="center">yuque-ai-mcp</h1>
<p align="center">
<b>65 MCP tools (45 OpenAPI + 20 web-API)</b>
</p>
<p align="center">
<a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/version-4.0.0-blue" alt="version" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
<a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-67%20guides-orange" alt="skills" /></a>
</p>
<p align="center">
<a href="README_CN.md">中文文档</a>
</p>
---
A full-featured Yuque (语雀) MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). Provides 65 fine-grained tools across 13 domains — 45 Yuque OpenAPI endpoints plus 20 web-API tools requiring a browser session cookie.
## Why
- **19 → 65 tools** — 3x more coverage than the official [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server)
- **Dual transport** — stdio + HTTP SSE, shared registry, zero downtime on reload
- **Modular architecture** — 13 domains, barrel exports, single source of truth registry
- **Full API coverage** — group, recycle, upload, statistics, versions, boards — all the missing pieces
- **[Skill layer](https://github.com/yehuoshun/yuque-ai-skills)** — 67 usage guides for AI agents
## Table of Contents
- [Quick Start](#quick-start)
- [Tool Overview](#tool-overview)
- [Architecture](#architecture)
- [Configuration](#configuration)
- [Error Handling](#error-handling)
- [Contributing](#contributing)
- [License](#license)
## Quick Start
```bash
cd server
npm install
npm run build
# Copy config template
cp config/config.example.json config/config.json
# Edit config.json with your Yuque API token
# Run
npm start # stdio mode
npm run dev:http # HTTP SSE mode (http://localhost:3099)
```
> **Note**: `npm run dev:http` uses `tsx` for hot-reload during development.
## Tool Overview
| Domain | Tools | Highlights |
|--------|-------|------------|
| **doc** | 15 | CRUD, versions, diff, batch get, import URL/file, cross-book copy, export, resource download |
| **repo** | 8 | CRUD, batch get, cross-book copy, full export (TOC-structure + INDEX/GRAPH) |
| **toc** | 3 | Get, update, batch update (createTitle/appendNode/removeNode/moveNode) |
| **search** | 3 | General search + RAG-enhanced search + Cookie web search |
| **user** | 3 | User info, heartbeat, group list |
| **group** | 3 | Member list, role change, delete member |
| **statistic** | 4 | Group/member/repo/doc statistics |
| **note** | 4 | CRUD + soft-delete/restore |
| **recycle** | 3 | List, restore, destroy (Cookie auth) |
| **upload** | 1 | File upload to Yuque CDN (Cookie auth) |
| **board** | 3 | Mindmap, flowchart, architecture diagram |
| **mine** | 7 | Book stacks, editor center, update/sort book stack (Cookie auth) |
| **web_doc** | 8 | Web API: get/list docs, repos, TOC, move/copy/delete catalog nodes (Cookie auth) |
| **Total** | **65** | |
**Auth split**: 45 tools use the OpenAPI (`X-Auth-Token`); 20 are Web API requiring Cookie + `x-csrf-token` — `web_doc` (8), `mine` (7), `recycle` (3), `upload` (1), `web_search` (1).
### All 65 Tools
| Tool | Domain | Description |
|------|--------|-------------|
| `yuque_hello` | user | 心跳检测,验证 Token 有效性 |
| `yuque_get_user` | user | 获取当前 Token 的用户详情 |
| `yuque_get_user_groups` | user | 获取用户所属的团队列表 |
| `yuque_search` | search | 通用搜索文档/知识库 |
| `yuque_rag_search` | search | RAG 检索增强搜索 + 自动获取文档内容 |
| `yuque_web_search` | search | Cookie 态 Web 搜索,返回完整文档对象 + 精确总数 + 高亮摘要 |
| `yuque_get_group_users` | group | 获取团队成员列表 |
| `yuque_update_group_user` | group | 变更团队成员角色 |
| `yuque_delete_group_user` | group | 删除团队成员 |
| `yuque_list_docs` | doc | 获取知识库文档列表 |
| `yuque_create_doc` | doc | 创建文档 |
| `yuque_get_doc` | doc | 获取文档详情(支持 ID 或 slug) |
| `yuque_update_doc` | doc | 更新文档 |
| `yuque_delete_doc` | doc | 删除文档 |
| `yuque_batch_get_docs` | doc | 批量获取文档详情(max 20) |
| `yuque_get_doc_versions` | doc | 获取文档历史版本列表 |
| `yuque_get_doc_version_detail` | doc | 获取文档历史版本详情 |
| `yuque_diff_doc_versions` | doc | 对比两个版本的行级差异 |
| `yuque_copy_doc` | doc | 单文档跨库复制 |
| `yuque_export_doc` | doc | 导出单篇文档为 Markdown 文件 |
| `yuque_export_resources` | doc | 下载文档中的图片/附件到本地 |
| `yuque_import_url` | doc | 从网页 URL 导入文档 |
| `yuque_import_file` | doc | 从本地文件导入文档 |
| `yuque_embed_url` | doc | 生成文档嵌入阅读器 URL |
| `yuque_get_toc` | toc | 获取知识库目录 |
| `yuque_update_toc` | toc | 更新知识库目录 |
| `yuque_batch_update_toc` | toc | 批量更新目录(createTitle/appendNode/removeNode/moveNode/prependDoc) |
| `yuque_list_repos` | repo | 获取知识库列表(用户/团队) |
| `yuque_create_repo` | repo | 创建知识库 |
| `yuque_get_repo` | repo | 获取知识库详情 |
| `yuque_update_repo` | repo | 更新知识库 |
| `yuque_delete_repo` | repo | 删除知识库 |
| `yuque_batch_get_repos` | repo | 批量获取知识库详情(max 20) |
| `yuque_copy_repo` | repo | 批量跨库复制(LLM 分类 + 目录重建) |
| `yuque_export_repo` | repo | 批量导出知识库为 Markdown(按 TOC 目录结构) |
| `yuque_get_group_statistics` | statistic | 获取团队汇总统计数据 |
| `yuque_get_member_statistics` | statistic | 获取团队成员统计数据 |
| `yuque_get_book_statistics` | statistic | 获取团队知识库统计数据 |
| `yuque_get_doc_statistics` | statistic | 获取团队文档统计数据 |
| `yuque_list_notes` | note | 获取小记列表 |
| `yuque_get_note` | note | 获取小记详情 |
| `yuque_create_note` | note | 创建小记 |
| `yuque_update_note` | note | 更新小记 |
| `yuque_list_recycles` | recycle | 列出回收站项目(Cookie) |
| `yuque_restore_recycle` | recycle | 恢复回收站项目(Cookie) |
| `yuque_destroy_recycle` | recycle | 彻底删除回收站项目(Cookie) |
| `yuque_upload_attachment` | upload | 上传文件到语雀 CDN(Cookie) |
| `yuque_get_board` | board | 获取文档中的画板资源 |
| `yuque_create_board` | board | 在文档中创建画板资源 |
| `yuque_update_board` | board | 更新文档中的画板资源 |
| `yuque_get_book_stacks` | mine | 获取知识库分组(书架)列表(Cookie) |
| `yuque_get_editor_center` | mine | 获取个人编辑中心全景数据(Cookie) |
| `yuque_create_book_stack` | mine | 创建知识库分组(书架),内部 create 后自动改名(Cookie) |
| `yuque_rename_book_stack` | mine | 重命名知识库分组(书架)(Cookie) |
| `yuque_update_book_stack` | mine | 移动知识库到指定分组(书架)(Cookie) |
| `yuque_sort_book_stack` | mine | 排序知识库分组(书架)(Cookie) |
| `yuque_delete_book_stack` | mine | 删除知识库分组(书架),需 confirm='DELETE'(Cookie) |
| `yuque_web_get_doc` | web_doc | Cookie 态读文档正文(含 body/content),不受会员过期限流;`id` 支持文档 slug |
| `yuque_web_list_docs` | web_doc | Cookie 态列文档列表,更丰富的字段 |
| `yuque_web_list_repos` | web_doc | Cookie 态列知识库列表,含权限信息 |
| `yuque_web_get_toc` | web_doc | Cookie 态获取知识库目录 TOC |
| `yuque_web_delete_doc` | web_doc | Cookie 态删除文档(移入回收站,v2 被限流时的备用通道) |
| `yuque_web_move_catalog_node` | web_doc | Cookie 态移动目录节点 |
| `yuque_web_copy_catalog_node` | web_doc | Cookie 态复制目录节点 |
| `yuque_web_batch_move_catalog_nodes` | web_doc | Cookie 态批量移动目录节点 |
See [SKILL.md](SKILL.md) or [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills) for full tool documentation with parameters and examples.
## vs Official
| Feature | Official yuque-mcp-server | yuque-ai-mcp |
|---------|--------------------------|--------------|
| Tools | 19 | **65** |
| Granularity | Coarse | **Fine-grained** (1 tool / endpoint) |
| Group, Recycle, Upload, Statistics | ❌ | ✅ |
| Versions, Diff, Cross-book Copy | ❌ | ✅ |
| Transport | stdio only | **stdio + HTTP SSE** |
| Config | Env var | **config.json** (token + cookie) |
| Skill Layer | ❌ | ✅ 67 guides |
## Architecture
```
server/src/
├── common/ # Shared: config, errors, types, format, validate,
│ # api-client, web-request, register-tools, copy/export common,
│ # toc-cache (configurable TTL), text-utils
├── user/ search/ group/ doc/ toc/ repo/ statistic/
├── note/ recycle/ upload/ board/ mine/ web-doc/
├── index.ts # stdio entry
└── http.ts # HTTP SSE entry (port 3099)
```
## Configuration
```json
{
"token": "Your Yuque API Token",
"api_base": "https://www.yuque.com/api/v2",
"cookie": "Optional, for recycle/upload features",
"ctoken": "Optional, extracted from Cookie"
}
```
- `toc_cache_ttl_minutes`: TOC cache TTL in minutes (default 60). Set higher to reduce API calls, lower for fresher data.
## Error Handling
Unified error handling with structured responses (HTTP status + message + response summary). All tools share the same error pipeline.
Key errors:
- `book_full` — Auto-expands by creating a new repo and appending to the `book_id` array
- `401` / `403` — Token/permission issues
- `429` — Rate limit with automatic retry
See [references/api/errors.md](references/api/errors.md) for the full error code reference.
## Contributing
```bash
git clone https://github.com/yehuoshun/yuque-ai-mcp.git
cd yuque-ai-mcp/server
npm install
npm run build
# New tool checklist:
# 1. Create server/src/{domain}/{tool}.ts
# 2. Export in {domain}/index.ts + append to tools array
# 3. npx tsc
# 4. Restart HTTP server + curl health
# 5. Sync yuque-ai-skills
# 6. Update README
# 7. Sync awesome-list entries when tool/domain count changes
```
Both [yuque-ai-mcp](https://github.com/yehuoshun/yuque-ai-mcp) and [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills) are kept in sync.
## Maintenance
This project is listed in these directories. When the tool count or domain count changes, sync the entries (they mention "65 tools" / "13 domains"):
- [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
- [zackchewa/awesome-china-mcp](https://github.com/zackchewa/awesome-china-mcp)
## Tech Stack
- TypeScript + Node.js
- @modelcontextprotocol/sdk v1.x
- Zod (validation)
- Yuque OpenAPI v2 / Web API
## License
MITTDQS
Scored across 65 tools
The server exposes two parallel API surfaces (v2 token-based and cookie-based `web_*`) that largely duplicate each other: `yuque_list_docs`/`yuque_web_list_docs`, `yuque_get_doc`/`yuque_web_get_doc`, `yuque_get_toc`/`yuque_web_get_toc`, and `yuque_delete_doc`/`yuque_web_delete_doc` do the same job with slightly different payloads. Similarly, TOC restructuring is split across `yuque_update_toc`, `yuque_batch_update_toc`, `yuque_web_move_catalog_node`, and `yuque_web_batch_move_catalog_nodes`, and search is split across `yuque_search`, `yuque_rag_search`, and `yuque_web_search`. Descriptions hint at the differences (no membership required, richer fields, batch vs single), but an agent must read carefully to avoid picking the wrong twin.
Almost all tools follow `yuque_verb_noun` snake_case (`yuque_create_doc`, `yuque_list_repos`, `yuque_update_toc`), with a consistent `yuque_web_` prefix marking the cookie-based variants. Minor deviations exist (`yuque_hello` has no verb, `yuque_rag_search` inserts a modifier), but the pattern is predictable and readable overall.
65 tools is far beyond a comfortable surface for an agent to navigate, and the count is inflated by the duplicate v2/web API pairs plus four separate TOC-manipulation tools. The domain (docs, repos, TOC, notes, groups, boards, search, recycle, statistics, book stacks) is genuinely broad, so some size is justified, but this many tools with this much redundancy is heavy.
Coverage is unusually thorough: full CRUD for docs, repos, notes, boards, and book stacks, plus TOC editing, recycle bin lifecycle, version history/diff, export/import, group member management, and statistics. Gaps are minor and peripheral — no comment/discussion tools and no explicit permission/share management for documents or repos.