Cloudreve v4 MCP

Standalone Model Context Protocol server for Cloudreve v4. It authenticates with a registered OAuth application (authorization code + PKCE), then exposes file and local-cache tools over stdio for Cursor and other MCP clients.

Not published on npm — run it with npx from GitHub (github:SanderCokart/cloudreve-mcp).

Features

• OAuth authorize / status / logout with secure local token storage
• File tools: list, resolve id, properties, download URL, download, upload, create directory, rename, move, copy, delete, source URL, share URL
• Local cache helpers: list, write text, presign, download-to-cache, upload-from-cache
• Cloudreve v4 File URIs (cloudreve://my/...) with friendly /path inputs

Prerequisites

1. Node.js 20+
2. A Cloudreve v4 site (this MCP uses /api/v4/...)
3. An OAuth app created in Cloudreve admin

Register an OAuth app

In Cloudreve admin → OAuth applications, create an app with:

Field	Value
App name	e.g. Cursor Cloudreve MCP
Client secret	Generate and store securely
Redirect URI	http://127.0.0.1:53682/callback (must match CLOUDREVE_REDIRECT_URI)
Scopes	At least openid, profile, offline_access, plus file scopes such as Files.Read, Files.Write, Shares.Read, Shares.Write (exact names depend on your Cloudreve build)

Copy the Client ID and Client Secret. Do not commit them to git or share them publicly.

offline_access is required to receive a refresh token.

Cursor MCP setup

Add to ~/.cursor/mcp.json (Windows: %USERPROFILE%\.cursor\mcp.json):

{
  "mcpServers": {
    "cloudreve": {
      "command": "npx",
      "args": [
        "-y",
        "github:SanderCokart/cloudreve-mcp"
      ],
      "env": {
        "CLOUDREVE_BASE_URL": "https://cloud.example.com",
        "CLOUDREVE_CLIENT_ID": "YOUR_CLIENT_ID",
        "CLOUDREVE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "CLOUDREVE_REDIRECT_URI": "http://127.0.0.1:53682/callback",
        "CLOUDREVE_SCOPES": "openid profile offline_access Files.Read Files.Write Shares.Read Shares.Write"
      }
    }
  }
}

Replace https://cloud.example.com and the OAuth placeholders with your own values. Endpoint overrides are optional; they are derived from CLOUDREVE_BASE_URL when omitted.

Reload MCP servers / restart Cursor, then call the authorize tool once. A browser window opens; after you approve, tokens are saved locally and other tools work.

Run from the terminal

npx -y github:SanderCokart/cloudreve-mcp

Set the same environment variables as in the Cursor env block before running.

Prefer github:SanderCokart/cloudreve-mcp over the GitHub .tar.gz archive URL. The archive install skips the package build on some platforms (notably Windows), so the cloudreve-mcp binary is missing.

Environment

Variable	Required	Description
CLOUDREVE_BASE_URL	Yes	Your Cloudreve site, e.g. https://cloud.example.com
CLOUDREVE_CLIENT_ID	Yes	OAuth Client ID
CLOUDREVE_CLIENT_SECRET	Yes	OAuth Client Secret
CLOUDREVE_AUTH_ENDPOINT	No	Authorization endpoint (default: {BASE}/session/authorize)
CLOUDREVE_TOKEN_ENDPOINT	No	Token endpoint (default: {BASE}/api/v4/session/oauth/token)
CLOUDREVE_REFRESH_ENDPOINT	No	Refresh endpoint (default: {BASE}/api/v4/session/token/refresh)
CLOUDREVE_USERINFO_ENDPOINT	No	User-info endpoint (default: {BASE}/api/v4/session/oauth/userinfo)
CLOUDREVE_REDIRECT_URI	No	Default http://127.0.0.1:53682/callback
CLOUDREVE_SCOPES	No	Space-separated scopes (see defaults above)
CLOUDREVE_DOWNLOAD_ROOT	No	Local download root
CLOUDREVE_CACHE_ROOT	No	Local cache root
CLOUDREVE_TOKEN_STORE	No	Path to tokens JSON (mode 0600)

Tokens are stored under the platform config dir by default:

• Windows: %APPDATA%/cloudreve-mcp/tokens.json
• macOS: ~/Library/Application Support/cloudreve-mcp/tokens.json
• Linux: ~/.config/cloudreve-mcp/tokens.json

First-run flow

sequenceDiagram
  participant Cursor
  participant MCP as CloudreveMCP
  participant Browser
  participant Cloudreve

  Cursor->>MCP: authorize
  MCP->>Browser: open /session/authorize (PKCE)
  Browser->>Cloudreve: user login + consent
  Cloudreve->>MCP: redirect code to localhost callback
  MCP->>Cloudreve: POST /api/v4/session/oauth/token
  Cloudreve->>MCP: access_token + refresh_token
  MCP->>MCP: persist tokens (0600)
  Cursor->>MCP: list_files / download_file / ...
  MCP->>Cloudreve: Bearer access_token on /api/v4/*

Install from source (contributors)

git clone https://github.com/SanderCokart/cloudreve-mcp.git
cd cloudreve-mcp
npm install
npm run build

For local Cursor config, point command at node and args at the built dist/index.js, and set the same env block as above.

Copy .env.example for a local checklist of variables (do not commit a filled .env).

Tool notes

• Paths may be /docs/a.md or full cloudreve://my/docs/a.md
• upload_file.remote_path must include the filename
• download_file.local_path is relative to CLOUDREVE_DOWNLOAD_ROOT and cannot escape it
• Upload supports local / relay policies fully; OneDrive and generic pre-signed chunk uploads are best-effort
• Cache tools operate only under CLOUDREVE_CACHE_ROOT

Development

npm run typecheck
npm test
npm run dev

License

Apache-2.0