Yuque MCP server

This MCP server enables AI models to interact with Yuque knowledge platform, providing tools for document management, searches, and statistical analysis through the Yuque API.

Installation

Prerequisites

• Node.js 18+ (recommended)
• Yuque account with API token

Setup Instructions

1. Clone the repository:

   git clone https://github.com/Henryhaoson/Yueque-MCP-Server.git
   cd Yueque-MCP-Server
   

2. Install dependencies:

   npm install
   

3. Create an environment file:

   cp .env.example .env
   

4. (Optional) Add your Yuque API token to the .env file:

   YUQUE_API_TOKEN=your_yuque_api_token_here
   

   You can also provide the token via query parameters when connecting to the server.

Usage

Running the Server

Development Mode

# HTTP server mode
npm run dev

# CLI stdio mode
npm run dev:cli

Production Mode

Build the project first:

npm run build

Then run in HTTP or CLI mode:

# HTTP server mode
npm run start

# CLI stdio mode
npm run start:cli

Docker Deployment

Using Docker Compose (Recommended)

1. Build and start the container:

   docker-compose up -d
   

2. View logs:

   docker-compose logs -f
   

3. Stop the service:

   docker-compose down
   

Configure via environment variables or in the .env file:

# Example .env file
PORT=3000
YUQUE_API_TOKEN=your_token_here
YUQUE_API_BASE_URL=https://www.yuque.com/api/v2

Manual Docker Setup

1. Build the Docker image:

   docker build -t yuque-mcp-server .
   

2. Run the container:

   docker run -d -p 3000:3000 --name yuque-mcp-server yuque-mcp-server
   

3. With environment variables:

   docker run -d -p 3000:3000 \
     -e YUQUE_API_TOKEN=your_token_here \
     -e YUQUE_API_BASE_URL=https://www.yuque.com/api/v2 \
     --name yuque-mcp-server yuque-mcp-server
   

Available MCP Tools

User and Document Management

• get_current_user - Get information about the authenticated user
• get_user_docs - Retrieve all documents for the current user
• get_user_repos - Get knowledge repositories for a specified user
• get_repo_docs - List all documents in a specific repository
• get_doc - Retrieve detailed content of a specific document
• create_doc - Create a new document in a specified repository
• update_doc - Update an existing document
• delete_doc - Remove a document from a repository
• search - Search for documents or content across Yuque

Team Statistics and Analysis

• get_group_statistics - Get summary statistics for a team
• get_group_member_statistics - Get statistics for team members
• get_group_book_statistics - Get statistics for team knowledge repositories
• get_group_doc_statistics - Get statistics for team documents

Integration with AI Models

This MCP server can be used with AI models that support the Model-Context-Protocol, allowing them to interact with Yuque through defined tools:

1. Start the MCP server
2. Connect to the server from a compatible client
3. AI models can now interact with Yuque data using the registered tools

Query Parameters for SSE Endpoint

When connecting to the SSE endpoint, you can override environment configurations with query parameters:

• accessToken: Override the Yuque API token set in the .env file
• baseUrl: Override the Yuque API base URL set in the .env file

Example:

http://localhost:3000/sse?accessToken=your_token_here&baseUrl=https://custom.yuque.api/v2

This allows dynamic configuration without modifying the .env file. Each SSE connection can use different configurations, enabling the same server instance to serve multiple users or environments simultaneously.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "yuque" '{"command":"npm","args":["run","start:cli"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "yuque": {
            "command": "npm",
            "args": [
                "run",
                "start:cli"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "yuque": {
            "command": "npm",
            "args": [
                "run",
                "start:cli"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect