Yuque MCP README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Yuque MCP listing page.
Yuque MCP Server
Let AI assistants read and write your Yuque (语雀) knowledge base
through 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:
Supported clients: claude-desktop · vscode · cursor · windsurf · cline · trae · qoder · opencode. Prefer an interactive flow? Run npx yuque-mcp setup.
Claude Code
Register the server directly:
Other MCP clients (generic config)
Any client that supports stdio transport works — see docs/clients.md for per-client config paths.
3. Restart your client and start asking.
Configuration
| Setting | Env var / CLI flag | Description |
|---|---|---|
| Token (required) | YUQUE_TOKEN / --token | Personal or team Yuque API token |
| Host (optional) | YUQUE_HOST / --host | Site or space host, e.g. https://your-space.yuque.com — required for space-bound team tokens and private deployments |
Site roots are normalized to /api/v2; when unset, the host defaults to https://www.yuque.com/api/v2.
Migrating from an older config?
YUQUE_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 | yuque_get_user | Get the authenticated user for the current token |
| Search | yuque_search | Search docs or repos, with paging |
| Books | yuque_list_books | List books (知识库) of a user |
yuque_get_book | Get a book by ID or namespace | |
yuque_create_book | Create a book | |
yuque_update_book | Update name, slug, description, or visibility | |
| Docs | yuque_list_docs | List docs in a book, with paging |
yuque_get_doc | Get full content — markdown, lake, or html | |
yuque_create_doc | Create a doc in a book | |
yuque_update_doc | Update a doc's body or metadata | |
| TOC | yuque_get_toc | Get a book's table of contents |
yuque_update_toc | Append or move a single TOC node | |
| Notes | yuque_list_notes | List notes (小记), with paging and status filter |
yuque_get_note | Get a note with full content | |
yuque_create_note | Create a note | |
yuque_update_note | Update a note | |
| Boards | yuque_get_resource | Read a board (mindmap / flowchart / diagram) from a doc |
yuque_create_resource | Create a board in a doc | |
yuque_update_resource | 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 |
|---|---|
YUQUE_TOKEN ... is required | Set YUQUE_TOKEN=YOUR_TOKEN or pass --token=YOUR_TOKEN |
401 Unauthorized | Token invalid or expired — regenerate it |
429 Rate Limited | Too many requests — wait a moment and retry |
410 Gone | Target permanently deleted or endpoint deprecated — check the doc/book exists |
| Tool not found | Update to the latest version: npx -y yuque-mcp@latest |
npx command not found | Install Node.js v18 or later |
Development
Architecture, tech stack, and the full tool contract live in docs/. Contributions are welcome — see CONTRIBUTING.md.
Links
- Yuque API docs
- Model Context Protocol
- Yuque AI Ecosystem — skills and plugins built on top of this server