Yuque

You can run a local MCP server that uses a headless browser to fetch and expose Yuque documents in Cursor. This server authenticates with a Cookie, retrieves documents by URL, namespace+slug, or via repository structure, and can search or list content from your Yuque knowledge bases.

How to use

After you have the Yuque MCP server running, you can perform practical actions from Cursor: fetch a single document by URL or by namespace and slug, search documents by keywords, view a full table of contents for a repository, or list all documents in a knowledge base. You don’t need to know the underlying fetching details—just provide the inputs Cursor needs and you’ll receive structured document data, including title, content, author, and basic statistics.

How to install

Prerequisites: Node.js and npm installed on your system. If you’re on macOS or Linux, ensure you have a recent Node.js version. Windows users should run in a PowerShell or Command Prompt with Administrator privileges if needed.

Step 1: Install dependencies for the Yuque MCP server.

Step 2: Configure environment variables by creating a project root .env file and optionally copy a template.

Step 3: Build the project to generate the runnable dist files.

Step 4: Configure Cursor to connect to the MCP server using a local stdio setup. You will run the server with a command that points to the compiled index.

Configuration and startup details

The server uses Cookie-based authentication to access Yuque content via a headless browser. You can provide either a single _yuque_session cookie value or a full Cookie header string. Optional base URL and default namespace can simplify usage for enterprise deployments and recurring requests.

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"]
    }
  }
}

Environment variables to configure

The following environment variables are used to customize how the Yuque MCP server connects and authenticates.

Required and optional variables you will set in your .env or in the mcp.json env block.

MCP configuration examples

Use the environment variables in a dedicated .env file for easy updates. Then reference the server in Cursor’s mcp.json.

# .env template (copy env.example and fill values)
# Yuque Cookie (required)
YUQUE_COOKIE=your-cookie-here

# Optional: enterprise Yuque base URL
YUQUE_BASE_URL=https://your-company.yuque.com

# Optional: default knowledge base namespace
YUQUE_NAMESPACE=username/repo

Cursor MCP configuration

Configure Cursor to load the Yuque MCP server by pointing to the compiled entry and using the same environment information.

{
  "mcpServers": {
    "yuque": {
      "command": "node",
      "args": ["/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"]
    }
  }
}

Starting the service

1. Save the configuration file.
2. Restart Cursor to pick up the new MCP connection.
3. Verify in Cursor that the Yuque MCP service shows as connected.

Usage examples in Cursor

Example 1: Get document details by URL. Enter a prompt that asks for the document information by its Yuque URL.

Example 2: Search documents within a repository by keywords, for instance by a term found in titles or descriptions.

Example 3: Display the repository structure to understand available documents and folders.

Example 4: List all documents in a knowledge base to get an overview.

MCP tools and endpoints

The server exposes a set of tools to fetch document data, build a table of contents, perform searches, and list documents.

• get-yuque-doc — fetch a single Yuque document by URL or by namespace and slug.

• get-yuque-toc — retrieve the full directory tree for a knowledge base.

• search-yuque-docs — search documents by a query within a knowledge base.

• list-yuque-docs — list all documents in a knowledge base.

Notes and tips

Cookie values expire; use a full Cookie string for more stability, and store them in a secure .env file to simplify updates without changing the code.

Enterprise deployments require setting YUQUE_BASE_URL to the correct Yuque domain, and the namespace should follow the username/repo format (Chinese characters supported).

Troubleshooting

If authentication fails, verify that the YUQUE_COOKIE is correct and that you are logged in to the Yuque site. If documents are inaccessible, confirm the namespace and URL are correct and that the account has access.

Ensure the MCP server path in Cursor mcp.json is an absolute path and that the dist/index.js file exists after building.

Security considerations

Do not commit real cookies to version control. Use a dedicated .env file and restrict access to the machine running the server. Regularly refresh cookies and review access permissions for enterprise deployments.

Development and build commands

Install dependencies, build, and run in a typical flow.

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode (optional)
npm run dev

# Format code (optional)
npm run format

Available tools

get-yuque-doc

Fetch a single Yuque document by URL or by namespace and slug, including basic info and full content.

get-yuque-toc

Retrieve the complete table of contents for a knowledge base, including folders and document titles/slugs.

search-yuque-docs

Search documents within a knowledge base by a query, matching titles and descriptions (case-insensitive).

list-yuque-docs

List all documents in a knowledge base along with basic information for each document.