Cloudreve MCP Server

基于 MCP（Model Context Protocol）的 Cloudreve 工具服务端（Python），供 Cursor 等 MCP 客户端调用。推荐流程：登入网盘 → 解析抖音/哔哩哔哩链接或搜索网易云音乐 → 下载视频/歌曲 → 上传到网盘（可返回直链）。使用 uv / uvx 启动。

项目结构（src 布局）

CloudreveMCP/
├── run.py              # 根目录启动脚本：uv run python run.py
├── pyproject.toml
├── README.md
├── .gitignore
└── src/
    └── mcp_cloudreve/
        ├── __init__.py
        ├── __main__.py      # python -m mcp_cloudreve
        ├── main.py          # 入口逻辑，mcp.run(sse)
        ├── server.py        # FastMCP 与工具注册
        ├── cloudreve.py     # Cloudreve API 客户端
        ├── douyin.py        # 抖音分享链接解析与无水印下载
        ├── bilibili.py      # 哔哩哔哩 WBI 签名、DASH/durl 下载（[参考](https://github.com/bei123/astrbot_plugin_so_vits_svc/blob/master/bilibili_api.py)）
        └── netease.py       # 网易云音乐搜索、eapi 加密、获取播放链接与下载（[参考](https://github.com/bei123/astrbot_plugin_so_vits_svc/blob/master/netease_api.py)）

---

一、启动服务

需已安装 uv（pip install uv 或见官网）。

在项目根目录执行（任选其一）：

# 方式一：根目录启动脚本（推荐）
uv run python run.py

# 方式二：命令行入口
uv run mcp-cloudreve

# 方式三：以模块方式运行
uv run python -m mcp_cloudreve

或使用 uvx（从 PyPI 拉取并运行，无需先 clone 本仓库时可用）：

uvx mcp-cloudreve

• 默认监听 3001 端口（避免与部分环境 8000 冲突）；可通过环境变量 PORT、HOST 修改。
• SSE 端点：GET http://localhost:3001/sse 建立 SSE 流；POST http://localhost:3001/messages?session_id=xxx 发送请求。平台 SSE 模板中的 url 填 http://localhost:3001/sse。

环境变量（可选）

变量	说明
PORT	服务端口，默认 3001
HOST	监听地址，默认 0.0.0.0
CLOUDREVE_BASE_URL	Cloudreve API 根地址，默认 https://cloudreve.2000gallery.art/api/v4

上传大文件若出现 413 Request Entity Too Large：
分块大小由 Cloudreve 创建会话时返回的 chunk_size 决定，客户端必须按该大小上传每个分块（不能改小），否则会报 Invalid Content-Length。413 表示请求体超过了 Cloudreve 或反向代理（如 Nginx）的请求体上限，需要由服务端/运维调大限制，本 MCP 无法绕过。

• 若你自建 Cloudreve 且前面有 Nginx：在 Nginx 配置里（http、server 或 location 中）增加或修改：client_max_body_size 200m;（或更大，需 ≥ 单块大小），然后 nginx -s reload。
• 若使用他人提供的 Cloudreve（如 cloudreve.2000gallery.art）：需联系站点管理员提高 API 或反向代理的请求体上限；或改用你自己能改 Nginx/配置的 Cloudreve 实例。

---

二、在平台中使用（含 SSE 模板）

1. 平台给的 SSE 模板

若平台要求填写「SSE」类型、并给出类似下面的模板，按下面方式填写即可：

{
  "transport": "sse",
  "url": "http://localhost:3001/sse",
  "headers": {},
  "timeout": 5,
  "sse_read_timeout": 300
}

• url：填 http://localhost:3001/sse（端口与启动时一致，默认 3001）。
• transport：保持 "sse"。
• headers：一般留空 {} 即可；如需鉴权再按平台要求加。
• timeout / sse_read_timeout：可按平台建议保留或适当调大。

服务端行为：

• GET 你填的 url（即 /sse）→ 建立 SSE 流，返回会话 ID。
• POST 到 /messages?session_id=xxx → 发送 JSON-RPC（会话 ID 由 GET 阶段得到）。

2. 在 Cursor 中使用

1. 打开 Cursor 设置：File → Preferences → Cursor Settings（或 Ctrl+,），搜索 MCP。
2. 在 MCP Servers 里添加本服务，例如在配置文件中加入（具体路径以 Cursor 文档为准，可能是 ~/.cursor/mcp.json 或项目内 .cursor/mcp.json）：

{
  "mcpServers": {
    "cloudreve": {
      "url": "http://localhost:3001/sse"
    }
  }
}

3. 确保本仓库里的服务已用 uv run mcp-cloudreve 在本地跑起来（默认 http://localhost:3001）。
4. 重启 Cursor 或重新加载 MCP，使新配置生效。

3. 使用方式

MCP 推荐流程（抖音/哔哩哔哩视频进网盘）：

1. 登入网盘：调用 cloudreve_login（邮箱、密码；若站点开验证码需先 cloudreve_get_captcha），拿到 access_token 与 refresh_token。
2. （可选）查存储策略：调用 cloudreve_list_storage_policies(access_token)，取要用的策略 id 作为上传时的 policy_id。
3. 抖音链接 → 网盘：cloudreve_upload_douyin_video(access_token, douyin_share_link, policy_id, ...)。流程：解析抖音分享链接 → 下载无水印视频到临时文件 → 创建/确认文件夹 → 上传 → 删临时文件 → 返回直链。
4. 哔哩哔哩链接 → 网盘：cloudreve_upload_bilibili_video(access_token, bilibili_share_link, policy_id, ..., cookie=...)。流程：解析 BV 号 → 获取 WBI 签名与播放地址（DASH 或 durl）→ 下载到临时文件（DASH 会合并音视频，多段会合并）→ 创建/确认文件夹 → 上传 → 删临时文件 → 返回直链。建议传 B 站 cookie：未登录时画质通常只有 360p/480p，传入登录后的 cookie 可获取 1080p 等更高画质；需要登录才能看的视频也必须传 cookie。需本机已安装 ffmpeg（DASH 音视频合并、多段合并）。
5. 网易云音乐 → 网盘：cloudreve_upload_netease_song(access_token, keyword_or_song_id, policy_id, ...)。MCP 流程：根据关键词或歌曲 ID 搜索/获取歌曲 → 获取最佳可用音质链接（无损/极高/标准）→ 下载到临时文件 → 将封面图（JPG）嵌入音频元数据（MP3 ID3 / FLAC picture） → 创建/确认文件夹 → 上传 → 删临时文件 → 返回直链。可选传 netease_cookie 以获取更高音质（如无损）；返回中含 cover_url 供展示。

其他常用能力：

• 刷新令牌：access_token 过期时可调用 cloudreve_refresh_token(refresh_token)，或在需要 token 的工具中传入 refresh_token，接口返回 401 时会自动刷新并重试。

• 上传本地/Base64 文件：cloudreve_upload_file（本地路径或 Base64 + 目标 URI + policy_id），上传完成后会自动尝试获取直链。

• 直链：cloudreve_create_direct_links（传入文件 URI 列表）为已有文件创建直链。

• 创建文件夹：cloudreve_create_folder(access_token, folder_uri)，如 cloudreve://my/douyin 或 cloudreve://douyin（会自动补为 cloudreve://my/douyin）。

• 工具列表（均在「先登录」前提下使用除验证码外的接口）：

  • cloudreve_get_captcha — 获取登录验证码（仅站点开启验证码时需要）
  • cloudreve_login — 密码登录，返回 access_token、refresh_token
  • cloudreve_refresh_token — 使用 refresh_token 刷新，返回新的 access_token 与 refresh_token（API 文档）
  • cloudreve_list_storage_policies — 获取当前用户可用的存储策略列表（上传时 policy_id 填返回的 id）（API 文档）
  • cloudreve_create_folder — 在网盘创建文件夹（如 cloudreve://my/douyin），祖先目录不存在会自动创建（API 文档）
  • cloudreve_create_upload_session — 创建上传会话（可传 refresh_token 以自动刷新）
  • cloudreve_upload_file_chunk — 上传单个分块（可传 refresh_token 以自动刷新）
  • cloudreve_upload_file — 上传整个文件（支持本地路径或 Base64），上传后自动获取直链（可传 refresh_token 以自动刷新）
  • cloudreve_create_direct_links — 为指定文件 URI 创建直链（可传 refresh_token 以自动刷新）
  • cloudreve_upload_douyin_video — 从抖音分享链接解析无水印视频、下载并上传到网盘，返回直链（可传 folder_uri、refresh_token、可选 target_uri）
  • cloudreve_upload_bilibili_video — 从哔哩哔哩链接解析 BV、下载视频（DASH/durl，需 ffmpeg）并上传到网盘，返回直链；建议传 cookie 以获取高画质（1080p）（可传 folder_uri、refresh_token、可选 target_uri）
  • cloudreve_upload_netease_song — MCP 流程：关键词/歌曲 ID → 获取最佳音质链接 → 下载 → 封面图嵌入音频元数据 → 上传网盘 → 返回直链；可选传 netease_cookie 以获取更高音质（可传 folder_uri、refresh_token、可选 target_uri）
  • echo / get_time — 示例工具

---

三、协议说明

本服务使用 SSE（Server-Sent Events）传输：

• GET http://localhost:3001/sse → 建立 SSE 流，服务端返回会话 ID（在 SSE 事件中）。
• POST http://localhost:3001/messages?session_id=<id> → 发送 JSON-RPC 请求（Python MCP SDK 使用 session_id 查询参数）。

适合使用平台提供的「SSE」模板、只需填一个 url 的场景；url 填 http://localhost:3001/sse 即可。