yuque-mcp

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=cursor

Supported 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_TOKEN

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

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

MIT