Content
# Yuque MCP Server
This is a Yuque MCP (Model Context Protocol) server for Cursor, allowing you to directly obtain document information from Yuque URLs or knowledge base namespaces within Cursor.
## 📌 Environment Variables Quick Reference
| Environment Variable | Required | Default Value | Description |
|----------------------|----------|---------------|-------------|
| `YUQUE_COOKIE` | ✅ | None | Yuque Cookie (single session or complete Cookie string) |
| `YUQUE_BASE_URL` | ❌ | `https://www.yuque.com` | Yuque base URL (required for private enterprise deployments) |
| `YUQUE_NAMESPACE` | ❌ | None | Default knowledge base namespace (e.g., `username/repo`, supports Chinese) |
**Quick Configuration Example**:
```bash
# .env file
YUQUE_COOKIE=your-cookie-here
YUQUE_BASE_URL=https://your-company.yuque.com # Required for enterprise users
YUQUE_NAMESPACE=username/repo # Optional
```
## Features
✨ **Core Features**:
- 📋 Get document details via Yuque URL or namespace + slug
- 🔍 Search for documents in the knowledge base (matching title and description)
- 📚 Get the complete table of contents (TOC) of the knowledge base
- 📝 List all documents in the knowledge base
- 🍪 Cookie-based authentication, available for free users
## Authentication Method and Implementation
This server uses **Cookie authentication + headless browser** to obtain Yuque documents:
- ✅ Uses Puppeteer headless browser to simulate real browser access
- ✅ Automatically logs in by setting Cookie
- ✅ Extracts document content directly from the page
- ✅ Bypasses API permission restrictions
- ✅ No Yuque Super Member required
### How to Obtain Cookie
Yuque MCP supports two Cookie configuration methods:
#### Method 1: Use only `_yuque_session` (Recommended, Simple)
1. Log in to the Yuque website (e.g., https://www.yuque.com or private enterprise deployment address)
2. Open the browser developer tools (press F12 or right-click → Inspect)
3. Switch to the **Application** or **Storage** tab
4. Find **Cookies** → corresponding Yuque domain on the left
5. Find the Cookie named `_yuque_session`
6. Copy its value (Value column)
#### Method 2: Use the complete Cookie string (More Stable)
1. After logging in to the Yuque website, open the browser developer tools (F12)
2. Switch to the **Network** tab
3. Refresh the page or visit any Yuque document
4. Click on any request and find **Request Headers**
5. Find the `Cookie:` field and copy the complete Cookie string
**Complete Cookie Example Format**:
```
lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx; current_theme=default; acw_tc=xxx
```
> ⚠️ **Note**:
> - Cookies expire (usually in a few days to a few weeks), and you need to obtain them again after they expire
> - Using the complete Cookie string is usually more stable, but it contains more sensitive information, so please keep it safe
## Installation Steps
### 1. Install Dependencies
```bash
cd yuque-mcp
npm install
```
### 2. Configure Environment Variables
Create a `.env` file in the project root directory. You can copy the `env.example` file as a template:
```bash
cp env.example .env
```
Then edit the `.env` file and fill in your configuration:
```bash
# Yuque Cookie (required)
# Method 1: Only the value of _yuque_session
YUQUE_COOKIE=n_FzpQWqYiQEgGAKM6Y9BYtxBrmoJD16z6Jfv4wlFVvUy3_O621jF6Gg9_6R59pueqqvebZW7EC6tqPoU6qD9A==
# Method 2: Complete Cookie string (recommended, more stable)
# YUQUE_COOKIE=lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx; current_theme=default
# Optional: Yuque base URL (required for private enterprise deployments)
# Public cloud users can leave it unset, the default is https://www.yuque.com
# YUQUE_BASE_URL=https://your-company.yuque.com
# Optional: Set the default knowledge base namespace
# After setting, you can directly get the document through the slug without specifying the namespace every time
# Supports Chinese usernames, for example: username/repo or 用户名/知识库名
# YUQUE_NAMESPACE=username/repo
```
> 💡 The project provides an `env.example` template file, which contains detailed configuration instructions
**Detailed Description of Environment Variables**:
| Environment Variable | Required | Description | Example |
|----------------------|----------|-------------|---------|
| `YUQUE_COOKIE` | ✅ Required | Cookie obtained from the browser, can be the value of a single `_yuque_session` or a complete Cookie string | See example above |
| `YUQUE_BASE_URL` | ❌ Optional | Yuque service address, required for private enterprise deployments | `https://company.yuque.com` |
| `YUQUE_NAMESPACE` | ❌ Optional | Default knowledge base namespace, format is `username/repo`, supports Chinese | `张三/我的知识库` |
**Configuration Suggestions**:
1. **Public Cloud Users**: Only need to configure `YUQUE_COOKIE`
2. **Enterprise Users**: Need to configure both `YUQUE_COOKIE` and `YUQUE_BASE_URL`
3. **Frequently Used Knowledge Bases**: It is recommended to configure `YUQUE_NAMESPACE` to simplify subsequent operations
### 3. Build Project
```bash
npm run build
```
### 4. Complete Configuration Examples
The following are complete configuration examples for different scenarios:
#### Scenario 1: Public Cloud Personal User (Simplest)
**.env File**:
```bash
YUQUE_COOKIE=n_FzpQWqYiQEgGAKM6Y9BYtxBrmoJD16z6Jfv4wlFVvUy3_O621jF6Gg9_6R59pueqqvebZW7EC6tqPoU6qD9A==
```
**mcp.json File**:
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"]
}
}
}
```
#### Scenario 2: Private Enterprise Deployment (Recommended Configuration)
**.env File**:
```bash
# Enterprise Yuque address
YUQUE_BASE_URL=https://your-company.yuque.com
# Complete Cookie string (more stable)
YUQUE_COOKIE=lang=zh-cn; _yuque_session=your-session-here; yuque_ctoken=your-token-here; current_theme=default
# Default knowledge base (supports Chinese)
YUQUE_NAMESPACE=username/your-repo-name
```
**mcp.json File**:
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"]
}
}
}
```
#### Scenario 3: Configure Directly in mcp.json (No .env Required)
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": ["/Users/username/Desktop/guanlink-mcp/yuque-mcp/dist/index.js"],
"env": {
"YUQUE_BASE_URL": "https://your-company.yuque.com",
"YUQUE_COOKIE": "lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx",
"YUQUE_NAMESPACE": "username/your-repo-name"
}
}
}
}
```
> 💡 **Tip**: It is recommended to use Scenario 2 (.env file) because you don't need to modify mcp.json when updating the Cookie
## Configure Cursor MCP
### Cursor Configuration File Location
- **macOS**: `~/.cursor/mcp.json` or `~/.config/cursor/mcp.json`
- **Linux**: `~/.config/cursor/mcp.json`
- **Windows**: `%APPDATA%\cursor\mcp.json`
### Method 1: Use .env File (Recommended)
Create a `.env` file in the project directory to configure environment variables, then edit Cursor's `mcp.json`:
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": [
"/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
]
}
}
}
```
**Advantages**:
- ✅ Environment variables are centrally managed for easy updating
- ✅ Configuration file is more concise
- ✅ Sensitive information is not exposed in mcp.json
### Method 2: Configure Environment Variables Directly in mcp.json
Suitable for scenarios where you don't want to create extra files:
#### Public Cloud Configuration Example (Simplest)
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": [
"/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
],
"env": {
"YUQUE_COOKIE": "your-session-cookie-value-here"
}
}
}
}
```
#### Private Enterprise Deployment Configuration Example
```json
{
"mcpServers": {
"yuque": {
"command": "node",
"args": [
"/Users/your-username/path/to/guanlink-mcp/yuque-mcp/dist/index.js"
],
"env": {
"YUQUE_BASE_URL": "https://your-company.yuque.com",
"YUQUE_COOKIE": "lang=zh-cn; _yuque_session=xxx; yuque_ctoken=xxx",
"YUQUE_NAMESPACE": "username/repo"
}
}
}
}
```
**Precautions**:
1. ⚠️ The path must be an **absolute path**
2. ⚠️ Windows users should pay attention to path separators, use `\\` or `/`
3. ⚠️ If the Cookie contains special characters, make sure they are properly escaped
4. ⚠️ `YUQUE_NAMESPACE` supports Chinese, such as `"用户名/知识库名"`
### Start Service
1. Save the configuration file
2. **Restart Cursor** for the configuration to take effect
3. In Cursor, you should see that the Yuque MCP service is connected
## Usage
After the configuration is complete, restart Cursor, and you can use the Yuque MCP service in Cursor.
### Example 1: Get Document Details
Enter in Cursor:
```
Please help me get the information of this Yuque document: https://www.yuque.com/username/repo/doc-slug
```
Or if you have set the default knowledge base namespace:
```
Please help me view the content of document doc-slug
```
### Example 2: Search Documents
```
Please search for documents containing "API" in the Yuque knowledge base username/repo
```
### Example 3: Get Knowledge Base Table of Contents
```
Please display the table of contents structure of the username/repo knowledge base
```
### Example 4: List All Documents
```
Please list all documents in the username/repo knowledge base
```
## MCP Tool Description
### 1. get-yuque-doc
Get detailed information of a single Yuque document.
**Parameters**:
- `docUrl` (string, optional): Yuque document URL
- `namespace` (string, optional): Knowledge base namespace, format is `username/repo`
- `slug` (string, optional): Document slug
**Supported Invocation Methods**:
```typescript
// Method 1: Use URL
{ docUrl: "https://www.yuque.com/username/repo/doc-slug" }
// Method 2: Use namespace + slug
{ namespace: "username/repo", slug: "doc-slug" }
// Method 3: If the default namespace is set, only provide slug
{ slug: "doc-slug" }
```
**Return Information**:
- Basic document information (title, ID, format, word count, etc.)
- Author information
- Knowledge base information
- Complete document content (Markdown or HTML)
- Statistics (views, likes, comments)
### 2. get-yuque-toc
Get the complete table of contents structure of the knowledge base.
**Parameters**:
- `namespace` (string, optional): Knowledge base namespace, if not provided, the default namespace is used
**Return Information**:
- Basic knowledge base information
- Complete document table of contents tree
- Title and slug of each document
### 3. search-yuque-docs
Search for documents in the knowledge base.
**Parameters**:
- `query` (string, required): Search keyword
- `namespace` (string, optional): Knowledge base namespace, if not provided, the default namespace is used
**Return Information**:
- List of matching documents
- Basic information of each document
> 📝 **Note**: The search will match keywords in the document title and description (case-insensitive).
### 4. list-yuque-docs
List all documents in the knowledge base.
**Parameters**:
- `namespace` (string, optional): Knowledge base namespace, if not provided, the default namespace is used
**Return Information**:
- Basic knowledge base information
- List of all documents
- Basic information of each document
## Project Structure
```
yuque-mcp/
├── src/
│ ├── index.ts # MCP server entry
│ └── lib/
│ ├── api.ts # Yuque API call
│ ├── browser-api.ts # Headless browser implementation
│ ├── types.ts # TypeScript type definition
│ └── utils.ts # Utility functions
├── dist/ # Compilation output directory
├── package.json
├── tsconfig.json
├── env.example # Environment variable configuration template
├── .env # Environment variable configuration (need to create based on env.example)
└── README.md
```
**Description of Important Files**:
- `env.example`: Environment variable configuration template, containing detailed comments
- `.env`: The actual environment variable file used (need to create by yourself, do not submit to git)
- `src/lib/browser-api.ts`: Headless browser solution implemented using Puppeteer
- `dist/`: JavaScript files compiled from TypeScript
## Development Commands
```bash
# Install dependencies
npm install
# Build
npm run build
# Development mode (build and run)
npm run dev
# Format code
npm run format
```
## Troubleshooting
### 1. Authentication Failed
**Symptoms**: Prompt "Yuque configuration verification failed" or "Cookie has expired"
**Solution**:
- ✅ Check if `YUQUE_COOKIE` is correct
- ✅ The Cookie may have expired, re-obtain it from the browser
- ✅ Make sure you are logged in to the Yuque website
- ✅ Try using the **complete Cookie string** instead of just `_yuque_session`
- ✅ Enterprise users check if `YUQUE_BASE_URL` is configured correctly
- ✅ Try clearing the browser cache, logging in again, and then obtaining a new Cookie
### 2. Unable to Get Document
**Symptoms**: Prompt "Unable to get document" or "Document does not exist"
**Check Items**:
- ✅ Is the document URL or namespace correct?
- ✅ Is the document a private document (requires login to access)?
- ✅ Does your Yuque account have permission to access the document?
- ✅ Is the Cookie valid?
- ✅ **Enterprise Users**: Confirm that `YUQUE_BASE_URL` is consistent with the actual domain being accessed
- ✅ If `YUQUE_NAMESPACE` is used, confirm that the format is correct (supports Chinese)
### 3. Cursor Cannot Find MCP Service
**Check Items**:
- ✅ Check if the path in `mcp.json` is correct (must be an **absolute path**)
- ✅ Make sure you have run `npm run build` to build the project
- ✅ Check if the `dist/index.js` file exists
- ✅ Restart Cursor
- ✅ View Cursor's MCP logs to confirm whether the service has started successfully
### 4. Cookie Expiration Frequency
The validity period of the Cookie depends on Yuque's settings, usually:
- If "Remember Me" is checked: a few weeks to a few months
- If not checked: a few days to a week
**Suggestions**:
1. Save the Cookie in the `.env` file, and only update the value in the file after it expires
2. Using the **complete Cookie string** usually has a longer validity period than a separate `_yuque_session`
3. Check and update the Cookie regularly (e.g., weekly)
### 5. Special Issues with Private Enterprise Deployment
**Symptoms**: Public cloud configuration is normal, but internal enterprise deployment cannot access
**Solution**:
- ✅ Confirm that the correct `YUQUE_BASE_URL` is set
- ✅ The URL format should be `https://your-company.yuque.com` (without a trailing slash)
- ✅ Confirm that the network can access the address (VPN may be required)
- ✅ The Cookie must be obtained from the corresponding enterprise Yuque domain and cannot be mixed
### 6. Chinese Namespace Cannot Be Recognized
**Symptoms**: An error is reported when using Chinese usernames or knowledge base names
**Solution**:
- ✅ `YUQUE_NAMESPACE` supports Chinese, format such as: `"用户名/知识库名"`
- ✅ Make sure the configuration file uses UTF-8 encoding
- ✅ If there are still problems, try using the English slug displayed in the URL instead of the Chinese name
## Security Recommendations
⚠️ **Important Note**:
### Cookie Security
- ❌ **Do not commit configuration files containing real Cookies to the code repository**
- ❌ **Do not share configurations containing Cookies on public platforms such as GitHub**
- ⚠️ Cookie is equivalent to your login credentials. If leaked, others can access your Yuque account
- 🔄 Update Cookie regularly (at least once a month is recommended)
- 🚨 If the Cookie is leaked, immediately log out of Yuque on all devices
### Best Practices for Environment Variable Management
1. **Use .env files** (recommended)
```bash
# Create a .env file in the project root directory
# Add to .gitignore to prevent submission
echo ".env" >> .gitignore
```
2. **Configure in mcp.json**
- mcp.json is usually in the user directory (`~/.cursor/mcp.json`) and will not be tracked by git
- But be careful not to leak it when backing up
3. **Extra attention for enterprise users**
- Enterprise Yuque may have stricter security policies
- Check session status regularly
- Consider using read-only accounts
### .gitignore Configuration Example
If your project uses git, make sure to add the following to `.gitignore`:
```gitignore
# Environment variables
.env
.env.local
.env.*.local
# Configuration files (if they contain sensitive information)
*-config.json
mcp.json
```
## Comparison with Jira MCP
| Feature | Jira MCP | Yuque MCP |
|------|----------|-----------|
| Authentication Method | Personal Access Token | Session Cookie |
| Free Users | ✅ Available | ✅ Available |
| Token Validity | Permanent or Custom | A few days to a few weeks |
| Configuration Difficulty | Easy | Easy |
| Manual Update Required | ❌ | ✅ (When Cookie expires) |
## Technology Stack
- **TypeScript**: Type-safe JavaScript
- **@modelcontextprotocol/sdk**: MCP Protocol SDK
- **Puppeteer**: Headless browser automation
- **Chromium**: Headless browser kernel
- **undici**: High-performance HTTP client (alternative)
- **zod**: Runtime type validation
## License
MIT License
## Related Links
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Yuque Open Platform](https://www.yuque.com/yuque/developer/api)
- [Cursor Official Website](https://cursor.sh/)
## Future Plans
- [ ] Support for getting document comments
- [ ] Support for getting all of a user's knowledge bases
- [ ] Support for batch exporting documents
- [ ] Optimize performance with caching mechanisms
- [ ] Support Token authentication (for super members)
---
If you have any questions or suggestions, please feel free to raise an Issue!
