io.github.yuque/yuque-mcp
MCP server for Yuque — expose your knowledge base to AI assistants.
Yuque MCP Server
MCP server for Yuque (语雀) — expose your knowledge base to AI assistants through the Model Context Protocol.
Quick Start
1. Get Your Yuque API Token
Visit Yuque Developer Settings to create a personal access token.
2. Quick Install (Recommended)
Use the built-in CLI to auto-configure your MCP client in one command:
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor
Supported clients: claude-desktop, vscode, cursor, windsurf, cline, trae, qoder, opencode
Or use the interactive setup wizard:
npx yuque-mcp setup
The CLI will automatically find the correct config file for your OS, merge with any existing configuration (without overwriting other servers), and print a success message.
3. Manual Configuration
Prefer to configure manually? Click to expand all client configs.
Choose your preferred client below:
Claude Code
claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN
Or using environment variables:
export YUQUE_PERSONAL_TOKEN=YOUR_TOKEN
claude mcp add yuque-mcp -- npx -y yuque-mcp
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"yuque": {
"command": "npx",
"args": ["-y", "yuque-mcp"],
"env": {
"YUQUE_PERSONAL_TOKEN": "YOUR_TOKEN"
}
}
}
}
VS Code (GitHub Copilot)
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"yuque": {
"command": "npx",
"args": ["-y", "yuque-mcp"],
"env": {
"YUQUE_PERSONAL_TOKEN": "YOUR_TOKEN"
}
}
}
}
Then enable Agent mode in GitHub Copilot Chat.
Cursor
Add to your Cursor MCP configuration (~/.cursor/mcp.json):
{
"mcpServers": {
"yuque": {
"command": "npx",
"args": ["-y", "yuque-mcp"],
"env": {
"YUQUE_PERSONAL_TOKEN": "YOUR_TOKEN"
}
}
}
}
Windsurf
Add to your Windsurf MCP configuration (~/.windsurf/mcp.json):
{
"mcpServers": {
"yuque": {
"command": "npx",
"args": ["-y", "yuque-mcp"],
"env": {
"YUQUE_PERSONAL_TOKEN": "YOUR_TOKEN"
}
}
}
}
Cline (VS Code)
Add to your Cline MCP settings (~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):
{
"mcpServers": {
"yuque": {
"command": "npx",
"args": ["-y", "yuque-mcp"],
"env": {
"YUQUE_PERSONAL_TOKEN": "YOUR_TOKEN"
}
}
}
}
Trae
In Trae, open Settings and navigate to the MCP section, then add a new stdio-type MCP Server with the following configuration:
- Command:
npx - Args:
-y yuque-mcp - Env:
YUQUE_PERSONAL_TOKEN=YOUR_TOKEN
See Trae MCP documentation for detailed instructions.
More clients: Any MCP-compatible client that supports stdio transport can use yuque-mcp. The general pattern is: command =
npx, args =["-y", "yuque-mcp"], env =YUQUE_PERSONAL_TOKEN.
4. Done!
Ask your AI assistant to search your Yuque docs, create documents, or manage books.
Authentication
The server supports multiple ways to provide your Yuque API token:
| Method | Environment Variable / Flag | Description |
|---|---|---|
| Personal Token (recommended) | YUQUE_PERSONAL_TOKEN | For accessing your personal Yuque account |
| CLI Argument | --token=YOUR_TOKEN | Pass directly as a command-line argument |
Priority order: YUQUE_PERSONAL_TOKEN > --token
Available Tools (16)
| Category | Tools |
|---|---|
| User | yuque_get_user |
| Search | yuque_search |
| Books | yuque_list_books, yuque_get_book, yuque_create_book, yuque_update_book |
| Docs | yuque_list_docs, yuque_get_doc, yuque_create_doc, yuque_update_doc |
| TOC | yuque_get_toc, yuque_update_toc |
| Notes | yuque_list_notes, yuque_get_note, yuque_create_note, yuque_update_note |
Troubleshooting
| Error | Solution |
|---|---|
YUQUE_PERSONAL_TOKEN is required | Set the environment variable YUQUE_PERSONAL_TOKEN or pass --token=YOUR_TOKEN |
401 Unauthorized | Token is invalid or expired — regenerate at Yuque Settings |
429 Rate Limited | Too many requests — wait a moment and retry |
410 Gone | The resource has been permanently deleted or the API endpoint is deprecated — verify the target document/repo still 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
Links
License
Installation
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y yuque-mcpSet up in your AI client
Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-yuque-yuque-mcp": {
"command": "npx",
"args": [
"-y",
"yuque-mcp"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencePackage
yuque-mcpnpmCompatible MCP Clients
io.github.yuque/yuque-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
- Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect. - Cursor
~/.cursor/mcp.jsonRestart Cursor for changes to take effect. - VS Code
.vscode/mcp.jsonReload VS Code window for changes to take effect. - Windsurf
~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect. - Claude Code
.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.