Yuque Knowledge Base Management MCP Server

Project Overview

This project, based on the FastMCP framework, provides an MCP server specifically for managing Yuque knowledge bases.
The server supports automatic recognition and creation of knowledge base groups, creation or updating of documents, retrieval of document details, document lists, and complete knowledge base directories, with support for paginated queries and structured data returns.
All operations are implemented based on the official Yuque API.

Environment Setup

Dependency Installation

Ensure that Python 3.8+ is installed, along with the necessary dependencies.
The main Python packages this project depends on include:

• fastmcp
• starlette
• requests
• python-dotenv

You can install these using the following command:
bash
pip install fastmcp starlette requests python-dotenv

If there is a requirements.txt file in the root directory of the project, you can also use:
bash
pip install -r requirements.txt

Environment Variable Configuration

Create a .env file in the root directory of the project and configure the following environment variables:

• YUQUE_SPACE_SUBDOMAIN: The subdomain of the Yuque space (used as the URL prefix to access the Yuque space, e.g., https://[SUBDOMAIN].yuque.com)
• DEFAULT_API_TOKEN: Default API access token (used for authentication when calling the Yuque API)
• DEFAULT_GROUP_LOGIN: Default group (team) alias (specifies the identifier of the Yuque group to be accessed)
• DEFAULT_BOOK_SLUG: Default knowledge base alias (a unique identifier for the Yuque document library, used to locate a specific document library)

Example:

YUQUE_SPACE_SUBDOMAIN=your_space_subdomain_here
DEFAULT_API_TOKEN=your_api_token_here
DEFAULT_GROUP_LOGIN=your_group_login_here
DEFAULT_BOOK_SLUG=your_book_slug_here

Additionally, these variables can also be passed through the MCP client request headers. An example configuration file is as follows:

json
{
"mcpServers": {
"yuque-mcp": {
"url": "http://192.168.125.89:8000/mcp",
"headers": {
"YUQUE_SPACE_SUBDOMAIN": "www",
"DEFAULT_API_TOKEN": "M4HeyBFsRmyNDsdfsdfsdf7ut3YFPX",
"DEFAULT_GROUP_LOGIN": "oxsdf47",
"DEFAULT_BOOK_SLUG": "vfgsd6"
}
}
}
}

Starting the Service

Run the main server program server.py, which supports multiple transport modes:

bash
python server.py --transport streamable-http

Available transport modes:

• streamable-http (default): Stream-based HTTP transport
• sse: Server-Sent Events (SSE) based transport
• stdio: Standard input/output stream-based transport

Tool Description

The server automatically loads all tool modules from the tools/ directory, mainly including:

• create_yuque_group(name: str)
  Creates a group (directory) within the Yuque knowledge base.

  Parameter description:

  • name (str): The name of the group to be created. This name should be unique within the current knowledge base.

• create_yuque_doc_in_group(...)
  Creates a document under a specified group in the designated Yuque knowledge base. If the group does not exist, it will first create the group, then create the document within it.

  Parameter description:

  • group_name (str): The name of the group. If the group does not exist, it will be automatically created.
  • doc_title (str): The title of the document to be created.
  • doc_body (str): The content of the document, supporting Markdown format.

• get_yuque_doc_list(group_login, book_slug, offset, limit)
  Retrieves a list of documents from the knowledge base, supporting pagination.

• get_yuque_doc_detail(...)
  Retrieves detailed content of a specified document.

• get_yuque_repo_toc(...)
  Retrieves the full table of contents structure of the knowledge base.

Usage Examples

Start the server using the default transport:

bash
python server.py

Specify the SSE transport mode:

bash
python server.py --transport sse

Important Concepts in Yuque Documentation

The API domain is https://www.yuque.com, but note that accessing resources within a space requires using the subdomain of that space.

URL Path:

Yuque URLs follow a certain format, such as https://www.yuque.com/yuque/developer/api. This includes the user or team's name, the identifier of the knowledge base, and the identifier of the document.

https://www.yuque.com/yuque/developer/api [Full document access path]
|
+-- yuque/ [Team or user login name (group_login)]
|
+-- developer/ [Knowledge base identifier (book_slug)]
|
+-- api [Document identifier (doc_slug)]## Yuque Document Authentication

All of Yuque's open APIs require token verification to access.

Personal User Authentication - Exclusive Benefit for Super Members

You can obtain the Token by clicking on your personal avatar in Yuque and entering the Personal Settings page, as shown in the following image:

Enterprise Team Authentication - Exclusive Benefit for Flagship Spaces

For teams within a space, you can obtain the token by entering the team settings page (only available for flagship spaces), as shown in the following image.

Contribution Guidelines

We welcome the submission of Issues and Pull Requests to improve features or fix issues.

Contact Information

If you have any questions, please contact the project maintainer.