io.github.yuque/yuque-mcp

<a href="https://www.yuque.com/"><img src="https://avatars.githubusercontent.com/u/34602419?s=200&v=4" width="96" alt="Yuque logo"></a>

Let AI assistants read and write your Yuque (语雀) knowledge base<br>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.

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

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.

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

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