About yuque-mcp
yuque-mcp is an MCP server for Yuque that lets AI assistants read and write a user's Yuque knowledge base. It suits people who keep documentation in Yuque, and supports both personal and space-bound team tokens.
Key features
- 01Search docs and repositories
- 02Manage books, docs and table of contents
- 03Read and write notes
- 04Read and update boards such as flowcharts
- 05Install into several clients with one command
Use cases
- 01Searching Yuque content and producing summaries
- 02Turning meeting notes into a book document
- 03Adding a flowchart to a design document
MCP support
The project is an MCP server that exposes 19 Yuque API tools to MCP clients, covering reading and writing of users, books, docs, table of contents, notes and boards.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y yuque-mcpYUQUE_PERSONAL_TOKENSecretYuque personal API token (get from https://www.yuque.com/settings/tokens). Use one of: YUQUE_PERSONAL_TOKEN, YUQUE_GROUP_TOKEN, or YUQUE_TOKEN.YUQUE_GROUP_TOKENSecretYuque group/team API token (alternative to YUQUE_PERSONAL_TOKEN for team workspaces).YUQUE_TOKENSecretYuque API token (legacy, use YUQUE_PERSONAL_TOKEN or YUQUE_GROUP_TOKEN instead).Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project README
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:
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor
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:
claude mcp add yuque -- npx -y yuque-mcp --token=YOUR_TOKEN
Other MCP clients (generic config)
Any 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.
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.
# Team token / private deployment
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor --host=https://your-space.yuque.com
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
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 reload
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
License
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.