Skip to main content
Glama

yuque-mcp

语雀 MCP 服务 - 基于语雀 OpenAPI 的 Model Context Protocol 服务,让 AI Agent(如 Qoder、Claude Desktop、Cursor 等)能够安全地访问和操作语雀知识库。

本服务是给 AI Agent 使用的 MCP 工具服务,不是手动运行的程序。安装后,AI Agent 会根据 MCP 配置自动启动本服务,通过 stdin/stdout 与之通信。你不需要手动运行它。

工作原理

AI Agent (Qoder / Claude Desktop / Cursor ...)
   │
   │  读取 MCP 配置,自动启动: yuque-mcp --permission read
   │  设置环境变量: YUQUE_TOKEN=xxx
   │
   ▼ 通过 stdin/stdout (JSON-RPC) 通信
yuque-mcp 进程
   │
   │  调用语雀 API
   ▼
语雀 API (https://www.yuque.com)

Related MCP server: Yuque MCP Server

特性

  • 基于语雀 OpenAPI 2.0.1 规范实现

  • 三级权限控制,默认只读,防止 AI 误操作

  • 支持 stdio 传输模式,兼容主流 MCP 客户端

  • 支持 Docker 部署

权限级别

级别

说明

可用操作

工具数

read (默认)

只读

GET 请求

14

write

读写

GET + POST/PUT/PATCH

22

admin

管理

所有操作包括 DELETE

25

快速开始

两种方式任选其一,都只需操作一次,之后 Agent 每次调用时自动拉起服务,无需手动启动。

方式一:本地安装(推荐,简单)

# 在项目目录下安装
pip install -e .

# 验证安装成功
yuque-mcp --version

安装后 yuque-mcp 命令注册到 PATH 中,Agent 自动找到并调用。

方式二:Docker(适合不想装 Python 的用户)

# 构建镜像(只需一次,镜像会留在本机)
docker build -t yuque-mcp .

构建后镜像 yuque-mcp:latest 永久存在本地。只有修改源码才需重新构建。

配置 MCP 客户端

在 AI Agent 的 MCP 配置中添加语雀服务,填入你的 Token 和权限级别即可。

你不需要手动运行服务,Agent 会根据配置自动启动它。

本地安装方式

所有 MCP 客户端(Claude Desktop、Cursor、Qoder 等)配置相同:

{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "args": ["--permission", "read"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com"
      }
    }
  }
}

Docker 方式

{
  "mcpServers": {
    "yuque": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "YUQUE_TOKEN", "-e", "YUQUE_BASE_URL", "yuque-mcp"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com"
      }
    }
  }
}

-i 保持 stdin 开放用于 MCP 通信,--rm 用完后自动清理容器。读写模式在 args 末尾加 "--permission", "write" 即可。

如果你的语雀团队使用了私有域名(如 jojoread.yuque.com),将 YUQUE_BASE_URL 改为对应的地址即可。

可用工具

只读工具(所有权限级别)

工具名

说明

yuque_hello

心跳检测

yuque_get_user_info

获取当前用户详情

yuque_get_user_groups

获取用户团队列表

yuque_get_user_repos

获取用户知识库列表

yuque_get_group_repos

获取团队知识库列表

yuque_get_repo

获取知识库详情

yuque_get_docs

获取文档列表

yuque_get_doc

获取文档详情

yuque_get_doc_by_book_id

通过知识库 ID 获取文档

yuque_get_toc

获取知识库目录

yuque_get_toc_by_book_id

通过知识库 ID 获取目录

yuque_get_doc_versions

获取文档历史版本列表

yuque_get_doc_version

获取文档历史版本详情

yuque_search

通用搜索

写入工具(write/admin 权限)

工具名

说明

yuque_create_repo

创建知识库

yuque_update_repo

更新知识库

yuque_create_doc

创建文档

yuque_update_doc

更新文档

yuque_create_doc_by_book_id

通过知识库 ID 创建文档

yuque_update_doc_by_book_id

通过知识库 ID 更新文档

yuque_update_toc

更新知识库目录

yuque_update_toc_by_book_id

通过知识库 ID 更新目录

删除工具(仅 admin 权限)

工具名

说明

yuque_delete_repo

删除知识库

yuque_delete_doc

删除文档

yuque_delete_doc_by_book_id

通过知识库 ID 删除文档

环境变量

在 MCP 客户端配置的 env 字段中设置:

变量名

必需

默认值

说明

YUQUE_TOKEN

是

-

语雀 API Token

YUQUE_PERMISSION_LEVEL

否

read

权限级别(read/write/admin)

YUQUE_BASE_URL

否

https://www.yuque.com

语雀 API 地址,私有域名时需修改

YUQUE_MCP_DEBUG

否

-

设为 1 开启 DEBUG 日志

获取语雀 Token

  1. 登录 语雀

  2. 进入 个人设置 → Token

  3. 创建一个新的 Token

调试

服务运行时日志输出到 stderr(MCP 协议使用 stdout),包含配置加载、API 请求/响应等信息。

开启 DEBUG 日志

在 MCP 客户端配置中添加 YUQUE_MCP_DEBUG 环境变量:

{
  "mcpServers": {
    "yuque": {
      "command": "yuque-mcp",
      "args": ["--permission", "read"],
      "env": {
        "YUQUE_TOKEN": "your_yuque_token_here",
        "YUQUE_BASE_URL": "https://www.yuque.com",
        "YUQUE_MCP_DEBUG": "1"
      }
    }
  }
}

日志示例

2026-06-10 15:28:33 [INFO] yuque_mcp: 配置初始化: base_url=https://www.yuque.com, token=qTGP3rqp..., permission=read, kwargs=[]
2026-06-10 15:28:33 [INFO] yuque_mcp: 创建 HTTP 客户端: base_url=https://www.yuque.com, token=qTGP3rqp...
2026-06-10 15:28:33 [INFO] yuque_mcp: API 请求: GET /api/v2/hello
2026-06-10 15:28:33 [INFO] yuque_mcp: API 响应: GET /api/v2/hello -> 200

常见问题

401 Unauthorized

如果日志显示 Token: (空),说明 YUQUE_TOKEN 环境变量未正确传入:

  • 确认 Token 写在 MCP 客户端配置的 env 字段中

  • 确认环境变量名是 YUQUE_TOKEN(不是 YUQUE_YUQUE_TOKEN)

  • 重启 MCP 客户端使配置生效

私有域名访问

如果你的语雀使用私有域名(如 xxx.yuque.com),需要设置 YUQUE_BASE_URL:

"YUQUE_BASE_URL": "https://xxx.yuque.com"

开发

# 安装开发依赖
pip install -e ".[dev]"

# 代码检查
ruff check src/

# 格式化
ruff format src/

License

Apache-2.0

Available Tools

14 tools
yuque_get_docB

获取文档详情

权限要求: read 参数:

  • group_login: 团队/用户 login

  • book_slug: 知识库 slug

  • id: 文档 ID

  • page_size: 评论每页数量 (可选)

  • page: 评论页码 (可选)

Inputs: group_login (required), book_slug (required), id (required), page_size, +1 more. Returns: result

yuque_get_doc_by_book_idA

通过知识库 ID 获取文档详情

权限要求: read 参数:

  • book_id: 知识库 ID

  • id: 文档 ID

  • page_size: 评论每页数量 (可选)

  • page: 评论页码 (可选)

Inputs: book_id (required), id (required), page_size, page. Returns: result

yuque_get_docsA

获取知识库的文档列表

权限要求: read 参数:

  • group_login: 团队/用户 login

  • book_slug: 知识库 slug

  • offset: 偏移量 (可选)

  • limit: 每页数量 (可选)

  • optional_properties: 附加属性 (可选, 如 body, body_html)

Inputs: group_login (required), book_slug (required), offset, limit, +1 more. Returns: result

yuque_get_doc_versionB

获取文档历史版本详情

权限要求: read 参数:

  • id: 版本 ID

Inputs: id (required). Returns: result

yuque_get_doc_versionsA

获取文档历史版本列表

权限要求: read 参数:

  • doc_id: 文档 ID

Inputs: doc_id (required). Returns: result

yuque_get_group_reposA

获取指定团队的知识库列表

权限要求: read 参数:

  • login: 团队 login

  • offset: 偏移量 (可选)

  • limit: 每页数量 (可选)

  • type: 知识库类型 (可选)

Inputs: login (required), offset, limit, type. Returns: result

yuque_get_repoA

获取知识库详情

权限要求: read 参数:

  • group_login: 团队/用户 login

  • book_slug: 知识库 slug

Inputs: group_login (required), book_slug (required). Returns: result

yuque_get_tocB

获取知识库目录

权限要求: read 参数:

  • group_login: 团队/用户 login

  • book_slug: 知识库 slug

Inputs: group_login (required), book_slug (required). Returns: result

yuque_get_toc_by_book_idC

通过知识库 ID 获取目录

权限要求: read 参数:

  • book_id: 知识库 ID

Inputs: book_id (required). Returns: result

yuque_get_user_groupsB

获取指定用户所属的团队列表

权限要求: read 参数:

  • id: 用户 ID 或 login

  • role: 角色过滤 (可选)

  • offset: 偏移量 (可选)

Inputs: id (required), role, offset. Returns: result

yuque_get_user_infoA

获取当前 Token 对应的用户详情

权限要求: read 返回: 用户信息,包含 id、login、name、avatar_url 等

Inputs: no named parameters. Returns: result

yuque_get_user_reposA

获取指定用户的知识库列表

权限要求: read 参数:

  • login: 用户 login

  • offset: 偏移量 (可选)

  • limit: 每页数量 (可选)

  • type: 知识库类型 (可选, 如 Book/Design/System)

Inputs: login (required), offset, limit, type. Returns: result

yuque_helloA

心跳检测 - 测试与语雀 API 的连接是否正常

权限要求: read

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some redundancy between `yuque_get_doc` and `yuque_get_doc_by_book_id` (and similarly for TOC). However, the descriptions clearly differentiate them by the way the book is specified.

    Naming Consistency5/5

    All tools follow a consistent `yuque_<verb>_<noun>` pattern, with variants like `_by_book_id` for clarity. No mixing of styles or inconsistent verbs.

    Tool Count5/5

    14 tools cover the main read operations for a knowledge base platform: document retrieval, version history, repositories, TOC, user info, groups, search, and heartbeat. The scope is well-balanced.

    Completeness2/5

    All tools are read-only; there are no create, update, or delete operations. For a comprehensive Yuque interaction, this is a major gap. The server appears to intentionally limit to read, but it lacks essential write capabilities.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers