Yuque MCP Server

Let AI assistants read and write your [Yuque (语雀)](https://www.yuque.com/) knowledge base
through the [Model Context Protocol](https://modelcontextprotocol.io/). [![CI][ci-image]][ci-url] [![npm version][npm-image]][npm-url] [![npm downloads][download-image]][download-url] [![License][license-image]][license-url] [Quick Start](#quick-start) · [Tools](#tools-19) · [Troubleshooting](#troubleshooting) · [Docs](./docs/README.md) · [中文文档](./README.zh-CN.md)

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](https://www.yuque.com/settings/tokens). 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: ```bash 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

Other MCP clients (generic config)

Any client that supports stdio transport works — see [docs/clients.md](./docs/clients.md) for per-client config paths. ```json { "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`. ```bash # 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](./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](./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](https://www.yuque.com/settings/tokens) | | `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](https://nodejs.org/) v18 or later | ## Development ```bash 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/](./docs/README.md). Contributions are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md). ## Links - [Yuque API docs](https://www.yuque.com/yuque/developer/api) - [Model Context Protocol](https://modelcontextprotocol.io/) - [Yuque AI Ecosystem](https://yuque.github.io/yuque-ecosystem/) — skills and plugins built on top of this server ## License [MIT](./LICENSE) [ci-image]: https://img.shields.io/github/actions/workflow/status/yuque/yuque-mcp-server/ci.yml?style=flat-square&label=CI [ci-url]: https://github.com/yuque/yuque-mcp-server/actions/workflows/ci.yml [npm-image]: https://img.shields.io/npm/v/yuque-mcp?style=flat-square [npm-url]: https://www.npmjs.com/package/yuque-mcp [download-image]: https://img.shields.io/npm/dm/yuque-mcp?style=flat-square [download-url]: https://www.npmjs.com/package/yuque-mcp [license-image]: https://img.shields.io/github/license/yuque/yuque-mcp-server?style=flat-square [license-url]: ./LICENSE