Yuque MCP Server
OfficialThe Yuque MCP Server connects AI assistants to your Yuque knowledge base, enabling full read/write management of content across the following areas:
User
Retrieve details about the current authenticated Yuque account
Search
Search for documents (
doc) or knowledge bases/repos (repo) by keyword
Books (知识库)
List, get, create, and update knowledge bases (name, slug, visibility, type)
Documents
List, get, create, and update documents within books, supporting Markdown, Lake, and HTML formats
Table of Contents (TOC)
Get and update a book's TOC (append, move, or reorganize nodes)
Notes (小记)
List, get, create, and update personal notes with pagination and status filtering
Structured Resources (Boards)
Read, create, and update board resources (mindmap, flowchart, architecture diagram) embedded in documents via text or JSON DSL
Additional features: supports personal/team tokens and custom hosts, with a CLI for easy setup with popular MCP clients (Claude Desktop, VS Code, Cursor, etc.).
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 Server search my Yuque docs for meeting notes"
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.
Let AI assistants read and write your Yuque (语雀) knowledge basethrough the Model Context Protocol.
Quick Start · Tools · Troubleshooting · Docs · 中文文档
Once connected, ask your assistant things like:
"Search my Yuque for everything about canary releases and give me a one-page summary."
"Turn today's meeting notes into a doc in my Tech Research book."
"Add a flowchart of this deployment pipeline to the design doc."
Quick Start
1. Get a token — create one at Yuque Developer Settings. If you use a team token bound to a Yuque space, also note the space host (e.g. https://your-space.yuque.com) — you will pass it as --host.
2. Install — one command locates the right config file for your OS and merges a yuque entry into it, without touching other servers:
npx yuque-mcp install --token=YOUR_TOKEN --client=cursorSupported clients: claude-desktop · vscode · cursor · windsurf · cline · trae · qoder · opencode. Prefer an interactive flow? Run npx yuque-mcp setup.
Register the server directly:
claude mcp add yuque -- npx -y yuque-mcp --token=YOUR_TOKENAny client that supports stdio transport works — see docs/clients.md for per-client config paths.
{
"mcpServers": {
"yuque": {
"command": "npx",
"args": ["-y", "yuque-mcp"],
"env": { "YUQUE_TOKEN": "YOUR_TOKEN" }
}
}
}3. Restart your client and start asking.
Related MCP server: Yuque MCP Server
Configuration
Setting | Env var / CLI flag | Description |
Token (required) |
| Personal or team Yuque API token |
Host (optional) |
| Site or space host, e.g. |
Site roots are normalized to /api/v2; when unset, the host defaults to https://www.yuque.com/api/v2.
# Team token / private deployment
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor --host=https://your-space.yuque.comYUQUE_PERSONAL_TOKEN, YUQUE_BASE_URL, and --base-url still work as legacy fallbacks. Precedence: YUQUE_TOKEN > YUQUE_PERSONAL_TOKEN > --token, and YUQUE_HOST > --host > YUQUE_BASE_URL > --base-url. New configs should use YUQUE_TOKEN and YUQUE_HOST.
Tools (19)
Each tool maps to exactly one Yuque API route.
Category | Tool | Description |
User |
| Get the authenticated user for the current token |
Search |
| Search docs or repos, with paging |
Books |
| List books (知识库) of a user |
| Get a book by ID or namespace | |
| Create a book | |
| Update name, slug, description, or visibility | |
Docs |
| List docs in a book, with paging |
| Get full content — markdown, | |
| Create a doc in a book | |
| Update a doc's body or metadata | |
TOC |
| Get a book's table of contents |
| Append or move a single TOC node | |
Notes |
| List notes (小记), with paging and status filter |
| Get a note with full content | |
| Create a note | |
| Update a note | |
Boards |
| Read a board (mindmap / flowchart / diagram) from a doc |
| Create a board in a doc | |
| Update a board in a doc |
In particular, yuque_update_doc cannot combine a markdown body with title / slug / public changes in a single call — update metadata separately. The full contract, including format routing between the YMD markdown API and the legacy document API, is documented in docs/capability-scope.md.
Not covered (yet): comments, attachment upload and file management, permission and member management, section-level doc edits, and structured resources other than boards.
Write access
The create/update tools modify real content in your knowledge base, and the server can do whatever your token can do. Keep the token secret, and prefer a space-scoped team token (with YUQUE_HOST) when you only work within one space. To report a vulnerability, see SECURITY.md.
Troubleshooting
Error | Solution |
| Set |
| Token invalid or expired — regenerate it |
| Too many requests — wait a moment and retry |
| Target permanently deleted or endpoint deprecated — check the doc/book exists |
Tool not found | Update to the latest version: |
| Install Node.js v18 or later |
Development
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 reloadArchitecture, tech stack, and the full tool contract live in docs/. Contributions are welcome — see CONTRIBUTING.md.
Links
Yuque AI Ecosystem — skills and plugins built on top of this server
License
Available Tools
19 toolsyuque_create_bookB
Create a new book (知识库) for the current user
Inputs: login (required), name (required), slug (required), description, +2 more.
yuque_create_docA
Create a new document in a repo/book
Inputs: repo_id (required), title (required), slug, body, +2 more.
yuque_create_noteB
Create a new note (小记)
Inputs: body (required).
yuque_create_resourceB
Create a structured resource in a Yuque document. Currently resource_type only supports board: mindmap, flowchart, or architecturediagram.
Inputs: resource_type (required), type (required), dsl (required), doc_id, +2 more.
yuque_get_bookB
Get a specific book (知识库) by ID or namespace
Inputs: repo_id (required).
yuque_get_docB
Get a specific document with full content
Inputs: repo_id (required), doc_id (required), format, include_lake.
yuque_get_noteB
Get a specific note with full content
Inputs: note_id (required).
yuque_get_resourceA
Read a structured resource view from a Yuque document. Currently resource_type only supports board; pass the raw resource_id, not board://<resource_id>.
Inputs: resource_type (required), resource_id (required), doc_id, url.
yuque_get_tocB
Get the table of contents (TOC) for a repo/book
Inputs: repo_id (required).
yuque_get_userA
Get current authenticated user information
Inputs: no named parameters.
yuque_list_booksB
List all books (知识库) for the current user
Inputs: login (required).
yuque_list_docsA
List all documents in a repo/book
Inputs: repo_id (required).
yuque_list_notesB
List all notes (小记) for the current user with pagination
Inputs: status, page, limit.
yuque_searchC
Search for documents or repos in Yuque
Inputs: query (required), type (required).
yuque_update_bookC
Update a book (知识库)
Inputs: repo_id (required), name, slug, description, +1 more.
yuque_update_docC
Update an existing document
Inputs: repo_id (required), doc_id (required), title, slug, +3 more.
yuque_update_noteC
Update an existing note
Inputs: note_id (required), body (required).
yuque_update_resourceA
Update a structured resource in a Yuque document. Currently resource_type only supports board; provide exactly one of text or dsl.
Inputs: resource_type (required), resource_id (required), doc_id, url, +2 more.
yuque_update_tocA
Update the table of contents (TOC) for a repo/book. The toc_data must be a single-operation JSON object (not an array). Required fields: "action" (e.g. "appendNode"), "action_mode" ("child" or "sibling"), "target_uuid" (empty string for root level). For new nodes: include "type" ("TITLE" or "DOC") and "title". To move existing nodes: use "node_uuid" instead. Example: {"action":"appendNode","action_mode":"child","target_uuid":"","type":"TITLE","title":"New Section"}
Inputs: repo_id (required), toc_data (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Each tool targets a specific resource type and action (e.g., create, get, list, update) with clear naming prefixes like yuque_create_book, yuque_get_doc, etc. No two tools have overlapping purposes, making selection unambiguous.
All tools follow a consistent 'yuque_verb_noun' pattern using lowercase snake_case. The verbs are uniform (create, get, list, update) and the nouns correspond to resource types (book, doc, note, resource, toc), ensuring predictability.
With 19 tools covering books, docs, notes, resources, TOC, search, and user info, the count is on the higher side but still reasonable for a platform with multiple resource types. Each tool serves a distinct purpose without redundancy.
The toolset lacks delete operations for any resource type (books, docs, notes, resources, TOC). There is also no listing for resources or TOC items. These gaps prevent full lifecycle management and may cause agent failures when cleanup is needed.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for AI dialogue using various LLM models via AceDataCloud
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
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
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Yuque (语雀) platform through MCP protocol, supporting knowledge base management, document operations, search, and team collaboration features.11MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol service that enables AI agents to securely access and operate Yuque knowledge bases via the Yuque OpenAPI.14Apache 2.0
- AlicenseBqualityDmaintenanceExposes Yuque knowledge base to AI assistants for searching, creating, and managing documents and books via the Model Context Protocol.25731 npm1MIT