Summary
Connects your Yuque knowledge base to MCP clients through the Yuque API, exposing 19 tools across documents, books, notes, and search. You can query your knowledge base, create and update documents, manage table of contents, and work with resources. Supports both yuque.com and private deployments via custom base URLs. Ships with a CLI installer that auto-configures Claude Desktop, Cursor, VS Code, Windsurf, and other clients in one command. Authentication uses personal access tokens from your Yuque developer settings. Useful when you're maintaining documentation or internal wikis in Yuque and want your AI assistant to read from and write to those repositories without context switching.
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
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
Featured
Fastest browser for AI agents to run web automation tasks, always free.
Download Free life-time →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Connect your Claude agent to live crypto prices and trading routes via 1inch
Get the MCP →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Configuration
YUQUE_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).
Categories
Registryactive
Packageyuque-mcp
TransportSTDIO
AuthRequired
UpdatedFeb 27, 2026
