Content
# Yuque MCP Server
[English Version](./README.en.md)
A Model-Context-Protocol (MCP) server for integrating with the Yuque API. This implementation is inspired by [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) and uses the [Yuque Open API](https://app.swaggerhub.com/apis-docs/Jeff-Tian/yuque-open_api/2.0.1).
## Overview
This server provides MCP tools for interacting with the Yuque knowledge base platform, allowing AI models to:
- Get user and document information
- Create, read, update, and delete documents
- Search for content in Yuque
- Get knowledge base information
- Get statistics and analytics
## Installation
### Prerequisites
- Node.js 18+ (Recommended)
- A Yuque account with an API token
### Setup
1. Clone this repository:
```
git clone https://github.com/Henryhaoson/Yueque-MCP-Server.git
cd Yueque-MCP-Server
```
2. Install dependencies:
```
npm install
```
3. Create a `.env` file based on `.env.example`:
```
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 choose to provide the token via a query parameter when connecting to the server, instead of setting it in the .env file.
## Usage
### Running the Server
#### Development Mode
```bash
# HTTP Server Mode
npm run dev
# CLI stdio Mode
npm run dev:cli
```
#### Production Mode
First, build the project:
```bash
npm run build
```
Then run in HTTP or CLI mode:
```bash
# HTTP Server Mode
npm run start
# CLI stdio Mode
npm run start:cli
```
### Deploy with Docker
This project provides Docker support, allowing you to easily containerize and deploy the server.
#### Using Docker Compose (Recommended)
1. Build and start the container:
```bash
docker-compose up -d
```
2. View logs:
```bash
docker-compose logs -f
```
3. Stop the service:
```bash
docker-compose down
```
You can set configuration items through environment variables or in the `.env` file:
```bash
# .env file example
PORT=3000
YUQUE_API_TOKEN=your_token_here
YUQUE_API_BASE_URL=https://www.yuque.com/api/v2
```
#### Manual Docker Usage
1. Build the Docker image:
```bash
docker build -t yuque-mcp-server .
```
2. Run the container:
```bash
docker run -d -p 3000:3000 --name yuque-mcp-server yuque-mcp-server
```
3. Use environment variables:
```bash
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
```
### MCP Tools
The Yuque MCP server provides the following tools:
#### User and Document Management
- `get_current_user` - Get information about the currently authenticated user, including user ID, username, avatar, and other basic Yuque account information.
- `get_user_docs` - Get a list of all knowledge base documents for the current user, including private and collaborative documents.
- `get_user_repos` - Get a list of knowledge bases for the specified user. A knowledge base is a collection of documents in Yuque.
- `get_repo_docs` - Get a list of all documents in a specific knowledge base, including document titles, update times, and other information.
- `get_doc` - Get the detailed content of a specific document in Yuque, including the body, modification history, and permission information.
- `create_doc` - Create a new Yuque document in the specified knowledge base, supporting multiple content formats (Markdown, HTML, Lake).
- `update_doc` - Update an existing document in Yuque, allowing modification of the title, content, or permission settings.
- `delete_doc` - Delete the specified document from the Yuque knowledge base. This operation is irreversible.
- `search` - Search for documents or knowledge base content in the Yuque platform, supporting scope and author filtering.
#### Team Statistics and Analysis
- `get_group_statistics` - Get aggregated statistics for the team, including the number of members, number of documents, read count, and interaction data.
- `get_group_member_statistics` - Get statistics for team members, including the number of edits, read count, and likes for each member.
- `get_group_book_statistics` - Get statistics for team knowledge bases, including the number of documents, word count, and read count for each knowledge base.
- `get_group_doc_statistics` - Get statistics for team documents, including the word count, read count, and comment count for each document.
## 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. For example:
1. Start the MCP server
2. Connect to the server from a compatible client
3. The AI model can now use the registered tools to interact with Yuque data
### Query Parameters for SSE Endpoint
When connecting to the SSE endpoint, you can override environment configurations via query parameters, which take precedence over environment variables:
- `accessToken`: Overrides the Yuque API token set in the .env file
- `baseUrl`: Overrides 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 you to dynamically configure the service without modifying the .env file, and the query parameters take precedence over environment variables. This is especially useful for multi-user environments or testing different API endpoints.
Each SSE connection can use different configurations, allowing the same server instance to serve different users or environments simultaneously.
## Development
### Project Structure
```
src/
├── config.ts # Server configuration
├── index.ts # Main entry point
├── cli.ts # CLI entry point
├── server.ts # MCP server implementation
└── services/
└── yuque.ts # Yuque API service
```
### Adding New Tools
To add a new tool, modify the `registerTools` method in `src/server.ts`.
## API Improvements
Recent updates have added the following features:
1. **Team Statistics**: Added the ability to obtain team, member, knowledge base, and document statistics, facilitating the analysis and monitoring of team knowledge base usage.
2. **Enhanced Document Management**:
- Support for multiple document formats (Markdown, HTML, Lake)
- Improved document visibility settings (private, public, public within the enterprise)
- Search function supports more parameters and filtering conditions
3. **Improved Data Types**: Updated interface definitions to align with the Yuque OpenAPI specification.
## License
ISC
## Acknowledgments
- [Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) provides a reference for MCP server implementation
- [Yuque Open API](https://app.swaggerhub.com/apis-docs/Jeff-Tian/yuque-open_api/2.0.1) provides API documentation
- [Model Context Protocol](https://github.com/anthropics/model-context-protocol) provides MCP specifications
