Yuque MCP Server

Yuque MCP Server Skill

Skill by ara.so — MCP Skills collection.

Overview

The Yuque MCP Server is a Model Context Protocol server that exposes the Yuque (语雀) knowledge base API to AI assistants. It allows you to search documents, create and update content, manage knowledge bases (books), and access resources through 19 different tools. Yuque is a collaborative documentation platform popular in China.

Key capabilities:

• Search across your Yuque knowledge base
• Create, read, and update documents
• Manage books (knowledge base collections)
• Handle resources (attachments, images)
• Manage table of contents and notes
• Support for both personal and team tokens
• Compatible with private Yuque deployments

Installation

Quick Install (Recommended)

Use the built-in CLI to auto-configure your MCP client:

# Interactive setup wizard
npx yuque-mcp setup

# Direct install with token
npx yuque-mcp install --token=$YUQUE_TOKEN --client=cursor

# With custom host for team/private deployment
npx yuque-mcp install --token=$YUQUE_TOKEN --client=cursor --host=https://your-space.yuque.com

Supported clients: claude-desktop, vscode, cursor, windsurf, cline, trae, qoder, opencode

Manual Configuration

Claude Code

export YUQUE_TOKEN=your_token_here
claude mcp add yuque-mcp -- npx -y yuque-mcp

Claude Desktop / Cursor / Windsurf

Add to config file (claude_desktop_config.json or mcp.json):

{
  "mcpServers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "yuque-mcp"],
      "env": {
        "YUQUE_TOKEN": "your_token_here"
      }
    }
  }
}

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "yuque": {
      "command": "npx",
      "args": ["-y", "yuque-mcp"],
      "env": {
        "YUQUE_TOKEN": "your_token_here"
      }
    }
  }
}

Authentication

Getting Your Token

1. Visit Yuque Developer Settings
2. Create a personal access token
3. Store it securely as YUQUE_TOKEN environment variable

Configuration Options

Priority order:

• Token: YUQUE_TOKEN > YUQUE_PERSONAL_TOKEN > --token
• Host: YUQUE_HOST > --host > YUQUE_BASE_URL > --base-url

Team Tokens and Private Deployment

# Environment variables
export YUQUE_TOKEN=your_token_here
export YUQUE_HOST=https://your-space.yuque.com

# CLI arguments
npx yuque-mcp --token=$YUQUE_TOKEN --host=https://your-space.yuque.com

Available Tools (19 Total)

User Tools

yuque_get_user - Get current user information

Search Tools

yuque_search - Search across all documents

• Parameters: q (query string), type (optional: "doc", "book", "user")
• Returns matching documents with snippets

Book Management

yuque_list_books - List all knowledge bases

• Parameters: user (optional: username or ID), type (optional: "Book", "Design")

yuque_get_book - Get book details

• Parameters: namespace (book identifier)

yuque_create_book - Create new knowledge base

• Parameters: name, slug, description (optional), public (optional)

yuque_update_book - Update book properties

• Parameters: namespace, name, slug, description, public

Document Management

yuque_list_docs - List documents in a book

• Parameters: namespace (book identifier)

yuque_get_doc - Get document content

• Parameters: namespace (book), slug (doc identifier)

yuque_create_doc - Create new document

• Parameters: namespace, title, slug (optional), body (markdown/html), format (optional: "markdown", "lake", "html")

yuque_update_doc - Update document

• Parameters: namespace, id, title, slug, body, format

Resource Management

yuque_get_resource - Get resource (attachment) details

• Parameters: namespace, id

yuque_create_resource - Upload resource

• Parameters: namespace, file (base64 or URL)

yuque_update_resource - Update resource metadata

• Parameters: namespace, id, title, description

Table of Contents

yuque_get_toc - Get book TOC structure

• Parameters: namespace

yuque_update_toc - Update TOC structure

• Parameters: namespace, toc (JSON structure)

Notes Management

yuque_list_notes - List personal notes

yuque_get_note - Get note content

• Parameters: id

yuque_create_note - Create personal note

• Parameters: title, body, format

yuque_update_note - Update note

• Parameters: id, title, body, format

Common Usage Patterns

Search Documents

Ask your AI assistant:

Search my Yuque docs for "API documentation"

The assistant will use yuque_search with your query.

Create a Document

Create a new document in my "engineering-notes" book titled "Deploy Process" with markdown content explaining our deployment workflow

The assistant will:

1. Find the book using yuque_list_books
2. Create the doc using yuque_create_doc

Update Existing Document

Update the "API Guide" document in my "docs" book to add a new section about authentication

The assistant will:

1. Find the document using yuque_get_doc
2. Update it using yuque_update_doc

Organize Knowledge Base

Show me all my Yuque books and their document counts

The assistant will use yuque_list_books and yuque_list_docs to gather information.

Development

Local Setup

git clone https://github.com/yuque/yuque-mcp-server.git
cd yuque-mcp-server
npm install

Build and Test

# Run tests
npm test

# Build TypeScript
npm run build

# Development mode with hot reload
npm run dev

Testing with MCP Inspector

# Set token
export YUQUE_TOKEN=your_token_here

# Run with inspector
npx @modelcontextprotocol/inspector npx yuque-mcp

Troubleshooting

Authentication Errors

Error: YUQUE_TOKEN ... is required

# Solution: Set environment variable
export YUQUE_TOKEN=your_token_here

# Or pass as argument
npx yuque-mcp --token=$YUQUE_TOKEN

Error: 401 Unauthorized

• Token is invalid or expired
• Regenerate at https://www.yuque.com/settings/tokens
• Verify token has correct permissions

Rate Limiting

Error: 429 Rate Limited

• Too many requests in short time
• Wait a moment before retrying
• Consider batching requests

Resource Not Found

Error: 410 Gone

• Resource has been permanently deleted
• API endpoint may be deprecated
• Verify the target document/book still exists in Yuque web interface

Connection Issues

Problem: Server not responding

# Check if server is running
ps aux | grep yuque-mcp

# Restart your MCP client
# For Claude Desktop: Quit and reopen
# For Cursor: Reload window (Cmd/Ctrl+R)

# Test connection manually
npx yuque-mcp

Version Issues

Problem: Tool not found

# Update to latest version
npx -y yuque-mcp@latest

# Clear npx cache if needed
rm -rf ~/.npm/_npx

Configuration Issues

Problem: Server not loading in client

1. Check config file location:

   • Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
   • Cursor: ~/.cursor/mcp.json
   • Windsurf: ~/.windsurf/mcp.json

2. Verify JSON syntax:

# Use jq to validate
cat ~/.cursor/mcp.json | jq .

3. Check logs:
   • Claude Desktop: View in app menu → "View Logs"
   • Cursor: Open Developer Tools (Cmd+Shift+P → "Toggle Developer Tools")

Node.js Not Found

Error: npx command not found

# Install Node.js (v18 or later)
# macOS
brew install node

# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# Windows: Download from https://nodejs.org/

Code Examples

TypeScript Integration

If you're building a custom MCP client or extending the server:

import { MCPClient } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', 'yuque-mcp'],
  env: {
    YUQUE_TOKEN: process.env.YUQUE_TOKEN
  }
});

const client = new MCPClient({
  name: 'my-yuque-client',
  version: '1.0.0'
});

await client.connect(transport);

// Call a tool
const result = await client.callTool({
  name: 'yuque_search',
  arguments: {
    q: 'API documentation'
  }
});

console.log(result);

Custom Tool Wrapper

interface YuqueConfig {
  token: string;
  host?: string;
}

class YuqueHelper {
  private config: YuqueConfig;
  
  constructor(config: YuqueConfig) {
    this.config = config;
  }
  
  async searchDocs(query: string, type?: string) {
    // Use MCP client to call yuque_search
    return await client.callTool({
      name: 'yuque_search',
      arguments: { q: query, type }
    });
  }
  
  async createDoc(namespace: string, title: string, body: string, format = 'markdown') {
    return await client.callTool({
      name: 'yuque_create_doc',
      arguments: { namespace, title, body, format }
    });
  }
}

Additional Resources

• Yuque API Documentation
• MCP Protocol Specification
• GitHub Repository
• Project Website