Yuque MCP Server

MCP server for Yuque (语雀) — expose your knowledge base to AI assistants through the Model Context Protocol.

🌐 Website · 📖 API Docs · 中文文档

Quick Start

1. Get Your Yuque API Token

Visit Yuque Developer Settings to create a personal access token. If you use a team token from a Yuque space, also prepare that space host, for example https://your-space.yuque.com.

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

Choose your preferred client below:

claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN

Or using environment variables:

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

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_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

Add to .vscode/mcp.json in your workspace:

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

Then enable Agent mode in GitHub Copilot Chat.

Add to your Cursor MCP configuration (~/.cursor/mcp.json):

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

Add to your Windsurf MCP configuration (~/.windsurf/mcp.json):

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

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_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}

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_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_TOKEN.

4. Done!

Ask your AI assistant to search your Yuque docs, create documents, or manage books.

Related MCP server: Yuque MCP Server

Authentication

The server supports multiple ways to provide your Yuque API token:

Token priority order: YUQUE_TOKEN > YUQUE_PERSONAL_TOKEN > --token

Host priority order: YUQUE_HOST > --host > YUQUE_BASE_URL > --base-url

YUQUE_PERSONAL_TOKEN, YUQUE_BASE_URL, and --base-url are kept as legacy fallbacks for existing configs. New configs should use YUQUE_TOKEN and YUQUE_HOST.

Team Tokens and Private Deployment

For team tokens, privately deployed Yuque instances, or custom Yuque spaces, set YUQUE_HOST or pass --host:

# Environment variable
export YUQUE_TOKEN=YOUR_TOKEN
export YUQUE_HOST=https://your-space.yuque.com

# CLI argument
npx yuque-mcp --token=YOUR_TOKEN --host=https://your-space.yuque.com

# Install with custom host
npx yuque-mcp install --token=YOUR_TOKEN --client=cursor --host=https://your-space.yuque.com

The host may be a Yuque site root such as https://www.yuque.com or a full API base URL such as https://www.yuque.com/api/v2. Host roots are normalized to /api/v2 at runtime. When not set, the default API base URL is https://www.yuque.com/api/v2.

Available Tools (19)

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

Links

• Website

• Yuque API Docs

• MCP Protocol

• MCP Registry

• Contributing

License

MIT