Yuque AI MCP

yuque-ai-mcp

65 MCP tools (45 OpenAPI + 20 web-API)

中文文档

A full-featured Yuque (语雀) MCP Server built on the Model Context Protocol. Provides 65 fine-grained tools across 13 domains — 45 Yuque OpenAPI endpoints plus 20 web-API tools requiring a browser session cookie.

Why

• 19 → 65 tools — 3x more coverage than the official yuque-mcp-server
• Dual transport — stdio + HTTP SSE, shared registry, zero downtime on reload
• Modular architecture — 13 domains, barrel exports, single source of truth registry
• Full API coverage — group, recycle, upload, statistics, versions, boards — all the missing pieces
• Skill layer — 67 usage guides for AI agents

Table of Contents

• Quick Start
• Tool Overview
• Architecture
• Configuration
• Error Handling
• Contributing
• License

Quick Start

cd server
npm install
npm run build

# Copy config template
cp config/config.example.json config/config.json
# Edit config.json with your Yuque API token

# Run
npm start              # stdio mode
npm run dev:http       # HTTP SSE mode (http://localhost:3099)

Note: npm run dev:http uses tsx for hot-reload during development.

Tool Overview

Auth split: 45 tools use the OpenAPI (X-Auth-Token); 20 are Web API requiring Cookie + x-csrf-token — web_doc (8), mine (7), recycle (3), upload (1), web_search (1).

All 65 Tools

See SKILL.md or yuque-ai-skills for full tool documentation with parameters and examples.

vs Official

Architecture

server/src/
├── common/              # Shared: config, errors, types, format, validate,
│                        # api-client, web-request, register-tools, copy/export common,
│                        # toc-cache (configurable TTL), text-utils
├── user/ search/ group/ doc/ toc/ repo/ statistic/
├── note/ recycle/ upload/ board/ mine/ web-doc/
├── index.ts             # stdio entry
└── http.ts              # HTTP SSE entry (port 3099)

Configuration

{
  "token": "Your Yuque API Token",
  "api_base": "https://www.yuque.com/api/v2",
  "cookie": "Optional, for recycle/upload features",
  "ctoken": "Optional, extracted from Cookie"
}

• toc_cache_ttl_minutes: TOC cache TTL in minutes (default 60). Set higher to reduce API calls, lower for fresher data.

Error Handling

Unified error handling with structured responses (HTTP status + message + response summary). All tools share the same error pipeline.

Key errors:

• book_full — Auto-expands by creating a new repo and appending to the book_id array
• 401 / 403 — Token/permission issues
• 429 — Rate limit with automatic retry

See references/api/errors.md for the full error code reference.

Contributing

git clone https://github.com/yehuoshun/yuque-ai-mcp.git
cd yuque-ai-mcp/server
npm install
npm run build

# New tool checklist:
# 1. Create server/src/{domain}/{tool}.ts
# 2. Export in {domain}/index.ts + append to tools array
# 3. npx tsc
# 4. Restart HTTP server + curl health
# 5. Sync yuque-ai-skills
# 6. Update README
# 7. Sync awesome-list entries when tool/domain count changes

Both yuque-ai-mcp and yuque-ai-skills are kept in sync.

Maintenance

This project is listed in these directories. When the tool count or domain count changes, sync the entries (they mention "65 tools" / "13 domains"):

• punkpeye/awesome-mcp-servers
• zackchewa/awesome-china-mcp

Tech Stack

• TypeScript + Node.js
• @modelcontextprotocol/sdk v1.x
• Zod (validation)
• Yuque OpenAPI v2 / Web API

License

MIT