cloudreve-mcp

lovecatchuan/cloudreve-mcp

3.2

If you are the rightful owner of cloudreve-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Cloudreve MCP Bridge exposes Cloudreve's API capabilities through the Model Context Protocol (MCP), enabling unified file management for clients supporting MCP.

Tools
14
Resources
0
Prompts
0

Cloudreve MCP Bridge

项目简介

本项目将 Cloudreve 的 API 能力通过 MCP（Model Context Protocol） 暴露，使得 Dify、Flowise、BiSheng（毕昇）等支持 MCP 的客户端可以以“工具”的形式调用 Cloudreve，实现统一的文件管理能力。 协议基于 JSON-RPC 2.0，并通过 SSE 通道进行初始化与消息推送。

已测试MCP Client

bisheng 1.3.1

配置（config.yaml）

server:
  host: 0.0.0.0
  port: 5001

cloudreve:
  base_url: https://pan.example.com   # 可写站点根或 API 根，客户端会自动补齐 /api/v3
  verify_ssl: true

paths:
  download_root: /data/download       # 所有下载一律落在此目录（启动时自动创建）

要点：

  • base_url 支持两种写法：https://pan.xxx.com 或 https://pan.xxx.com/api/v3；客户端会规范化处理，并修复双 /api/v3 的情况。
  • download_root 是服务端本机目录。所有下载都会强制落在这里，不会写到系统任意位置。

运行

pip install -r requirements.txt
python server.py

核心路由：

  • GET /sse：MCP SSE 通道（server → client 事件）
  • POST /mcp/message?client_id=...：MCP 客户端上行消息（JSON-RPC 2.0）
  • GET /mcp/config：MCP 工具清单（来自 app/mcp/tools.py）
  • GET /health：健康检查（{"status": "ready"} / {"status": "degraded"}）

日志：

  • 入站：app.middleware.request_logger 打印请求、响应与耗时
  • 出站（调用 Cloudreve）：app.clients.cloudreve 的 app.http 日志打印 方法/URL/重定向/状态/耗时/Content-Type/Length，用于定位 404 或重定向问题

多租户与认证模式

  • 推荐：无状态模式 每次工具调用在 arguments 中附 username、password 字段；base_url/verify_ssl 走配置，不对外暴露。 适合 BiSheng 等无需修改客户端源码的场景。
  • 可选：有状态模式 先调用 auth/login（绑定到 SSE client_id），之后的工具调用无需再传账号密码；auth/logout 可清理。

如使用 BiSheng 的 MCP Client，建议直接用无状态模式（每次带 username/password）。

工具清单与用法

工具定义见 app/mcp/tools.py；实现位于 app/services/handlers.py；Cloudreve 调用封装在 app/clients/cloudreve.py。

1) 列表 / 属性 / ID

  • list_files 入参：path（可空，默认根 /） 返回：目录信息，含 objects 等 {"path": "/docs"} → 返回该目录下对象列表（objects）、策略等。

  • get_file_id 入参：path（远程路径，如 /docs/1.md） 返回：唯一 id {"path": "/docs/1.md"} → 返回唯一 id。

  • get_file_properties 入参：file_id 返回：属性（大小、时间、类型、可选 path） {"file_id": "abc123"} → 返回大小、时间、类型等，可选返回 path。

2) 直链 / 下载

  • get_download_url {"file_id": "abc123"} → 返回可 GET 的绝对 URL（内部已处理 /api/v3 去重）。

  • download_file（已增强，强制下载到配置根目录） 入参：

    • file_id（必填）

    • local_path（选填，仅描述 download_root 下的相对位置）

    • （无状态时）username、password 规则：

    • 所有下载强制保存到 paths.download_root（默认 /data/download）

    • local_path 为相对 download_root 的路径，不会越权到系统其它目录

    • 若 local_path 看起来是目录（为空、以 / 结尾，或最后一段不含 . 扩展名），则在该目录下使用远端文件名保存

    • 若 local_path 是目录+文件名，则按该文件名保存

    • 自动创建父目录；目录穿越（如 ../../）会被拒绝 示例（假设远端文件名 report.pdf，download_root=/data/download）：

      • local_path="" → /data/download/report.pdf
      • local_path="tmp/" 或 "/tmp" → /data/download/tmp/report.pdf
      • local_path="tmp/1.md" → /data/download/tmp/1.md

3) 上传（必须使用“路径+文件名”）

  • upload_file 入参：

    • remote_path：远端完整路径（目录+文件名），如 /docs/1.md
    • local_path：服务端本机待上传文件路径，如 /data/download/tmp/1.md
    • （无状态时）username、password 行为：自动根据远端目录策略选择直传/分片上传；失败会抛错。

上传/下载都发生在服务端机器；客户端传的路径是告诉服务端“放/取哪里”，不是客户端本机路径。

4) 目录/文件操作（大多是“路径+文件名”的组合场景）

  • create_directory：{"path": "/docs/2025"} 新建目录
  • rename_file：{"file_id": "abc123", "new_name": "new.md"}
  • move_file：{"source_path": "/docs/1.md", "destination_path": "/dest"}（目标为目录）
  • copy_file：同上，目标为目录
  • get_share_url：生成分享，支持 is_dir/preview/downloads/expire/password
  • get_source_url：文件直链（支持单个或列表，返回绝对 URL）

5) 认证（有状态可选）

  • auth/login：{"username": "...", "password": "..."}
  • auth/logout：清理会话

如果每次工具都传 username/password，则无需调用 auth/login。

BiSheng（毕昇）示例

下载到默认根（自动用远端文件名）

{
  "name": "download_file",
  "arguments": {
    "file_id": "kREM3cn",
    "local_path": "",
    "username": "user@example.com",
    "password": "******"
  }
}

下载到子目录并改名

{
  "name": "download_file",
  "arguments": {
    "file_id": "kREM3cn",
    "local_path": "tmp/1.md",
    "username": "user@example.com",
    "password": "******"
  }
}

上传（远端必须是路径+文件名）

{
  "name": "upload_file",
  "arguments": {
    "remote_path": "/docs/report.pdf",
    "local_path": "/data/download/tmp/1.md",
    "username": "user@example.com",
    "password": "******"
  }
}

健康检查

  • GET /health

    • {"status": "ready"}：Cloudreve 初始化成功
    • {"status": "degraded"}：初始化失败（服务未退出），请检查日志

常见问题 & 排错

  • 下载 404：查看 app.http 出站日志是否有 .../api/v3/api/v3/...；当前版本已修复，如仍出现，请检查 cloudreve.base_url 是否重复带 /api/v3。
  • 下载文件是 404 页面：当前已做 HTTP 200 校验，失败会抛错而不会写入错误页；请确认 file_id 指向文件（非目录）且签名未过期。
  • 下载路径“乱跑”：本服务已强制把下载写入 paths.download_root，local_path 仅为相对路径描述。
  • 复制/移动失败：destination_path 是“目标目录”，如需改名请配合 rename_file。

License

Apache-2.0