Turn Baidu Netdisk into Your Cloud File Butler – A Complete, Hands-On Guide to the MCP Protocol

What exactly can Baidu Netdisk’s MCP Server do, and how can developers or individuals connect it to Claude/Cursor in under ten minutes to upload, search, share and manage files automatically?

1. TL;DR – the 30-second version

Baidu Netdisk now exposes every major feature (list, upload, copy, move, delete, share, semantic search, quota) through an MCP-compatible endpoint.
Get an access token, add two lines to your MCP client config, and you can:

  1. Upload local files, public URLs or raw text without opening the web UI.
  2. Ask in plain English “find the blue icon prototype I uploaded last March” and receive the file path, size and abstract.
  3. Batch-create share links with custom passwords and expiry dates, then paste the Markdown table straight into Notion.

The whole flow is no-code for readers and low-code for developers; the only prerequisite is a Baidu account.

2. Core questions this article answers

Section Reader’s question
2. Prep & token “How do I get credentials and verify the connection?”
3. Capabilities “Which file operations are covered, and when should I use which?”
4. Walk-throughs “Can you show me three real scenarios end-to-end?”
5. Deep dive “How do the atomic calls fit together, and what are the limits?”
6. Pitfalls “What are the first errors I will hit and how do I fix them?”

Each subsection starts with a one-sentence answer, then expands with examples, tables and author reflections.

2. Preparation & First Smoke Test

“How do I get credentials and verify the connection?”
Answer: Click the personal-auth link, copy the access token from the browser address bar, drop it into Cursor’s MCP config, and call user_info—if you see your avatar URL, you are in.

2.1 One-minute token retrieval (personal experience tier)

  1. Open this URL.
  2. Log in, press Authorise, look at the redirected URL starting with https://openapi.baidu.com/oauth/#access_token=.
  3. Copy the string between access_token= and the next &.
    Example: xxxxxxxxxx in
    https://openapi.baidu.com/oauth/#access_token=xxxxxxxxxx&expires_in=36000…
  4. Save it in an environment variable or paste directly into the config.

Author’s reflection: I kept forgetting to URL-encode the token when testing with curl; copying it verbatim into the JSON config removed that class of errors entirely.

2.2 Minimal MCP client config (SSE mode, upload excluded)

Cursor example:

{
  "mcpServers": {
    "baidu-netdisk": {
      "url": "https://mcp-pan.baidu.com/sse?access_token=xxxxxxxxxx"
    }
  }
}

Claude Desktop, Cline or any other SSE-compatible consumer works identically.
Restart the client; a green badge next to “baidu-netdisk” means the transport layer is healthy.

2.3 Smoke test – list root and check quota

Type into Agent mode:

list / and show quota

Expected return (abridged):

total: 2 147 483 648 000 B   (2 TB)
used:  573 440 000 000 B   (≈534 GB)
free:  1 574 043 648 000 B
expire_soon: false

Seeing numbers instead of auth errors proves both the SSE channel and the token are valid.

3. Capability Atlas – What You Can and Cannot Do

“Which file operations are covered, and when should I use which?”
Answer: Everything short of permanent private torrents is there; pick upload mode by file source, and prefer keyword search when you already know part of the name.

3.1 File information (read-only)

Tool Purpose When to use
file_list Enumerate any directory regardless of type Build tree views
file_doc_list Filter category = 4 (documents) Prepare full-text index
file_image_list category = 3 Quick gallery creation
file_video_list category = 1 Generate preview pages
file_meta Batch stat up to 10 fsids Verify after bulk move

All list variants accept:

  • dir – absolute path, URL-encoded
  • page – optional, starts at 1, 50 items per page default

Return fields always include: fsid, path, md5, category, size, filename, plus optional thumbnail, abstract, content (OCR or transcript when available).

3.2 Namespace management (write)

Tool Purpose Atomicity
make_dir Create single folder Always sync
file_copy Copy 1…N items Sync / adaptive / async
file_move Move 1…N items Same
file_del Delete 1…N items Same
file_rename Rename without moving Same

All write tools accept an ondup strategy:
fail | newcopy (auto-rename) | overwrite | skip
Default is newcopy, sparing newcomers from accidental overwrites.

Author’s reflection: I used overwrite once to sync nightly CI artifacts—because the build version is inside the filename, duplicates are impossible, and overwrite shaved 30 % time off the pipeline.

3.3 Upload trilogy – local, URL, text

Mode Input Size cap Notes
file_upload_stdio local file path 2 TB single file Requires Python stdio transport
file_upload_by_url public http(s) URL none Server pulls, good for VPS assets
file_upload_by_text string ≤ 20 000 chars 20 k chars Auto-saved as docx

Remote path defaults to /来自：mcp_server if you omit dir.
All three return at minimum: fsid, path, size, md5.

3.4 Search duo – keyword vs semantic

Type Param Strength Latency
Keyword key + optional dir Exact, sort by mtime desc Low
Semantic natural language query Concept match, returns abstract 1.2×…1.4× keyword

Both paginate through page & num.

3.5 Sharing & user info

Tool Inputs Output
file_sharelink_set fsid_list (JSON array string), period (days), pwd (4 char) link, short_url, pwd, period
user_info none avatar_url, vip_type, uk
get_quota none total, used, free, expire_soon

4. End-to-End Walk-Throughs

“Can you show me three real scenarios end-to-end?”
Answer: Below are (A) bulk screenshot archival, (B) fuzzy design file retrieval, and (C) batch-share-to-Notion, each with commands and returned snippets.

4.1 Scenario A – archive 200 PNG screenshots

Context
A content creator saves UI screenshots to ~/Desktop/shots daily. Goal: move them into /Project/Assets/Screenshots with zero clicks.

Steps

  1. Make sure stdio transport is configured (Python required for local upload).
  2. In Cursor Agent:

    make_dir /Project/Assets/Screenshots
upload local folder ~/Desktop/shots to /Project/Assets/Screenshots
  3. Cursor calls make_dir first (idempotent), then iterates file_upload_stdio.

Returned extract (one file)

{
  "filename": "shot_2024-05-16_14-02-36.png",
  "size": 432_128,
  "remote_path": "/Project/Assets/Screenshots/shot_2024-05-16_14-02-36.png",
  "fs_id": 1234567890,
  "status": "success"
}

Outcome
All 200 PNGs available in netdisk, each with thumbnail auto-generated; local folder can now be emptied safely.

Author’s reflection: I scheduled the same command as a Monday cron job; the feeling of opening netdisk and seeing an organised week’s worth of captures without dragging a mouse is oddly satisfying.

4.2 Scenario B – retrieve “blue icon prototype from March”

Context
A product manager remembers almost nothing except the colour and the month.

Command

semantic search query "blue icon prototype I uploaded around March"

Result

filename: blue-icon-v1.2.sketch
path: /Design/2024-Q1/blue-icon-v1.2.sketch
size: 3.1MB
abstract: 64px, 128px, 256px blue icons, colour #0052D9
thumbnail: https://thumbnail.url/xxxx.jpg

Because semantic search also returns fsid, she can chain:

share fsid 888888888 period 30 pwd z9qm

and drop the short link into Slack five seconds later.

4.3 Scenario C – batch-share ten PDF contracts to Notion

Context
Legal counsel needs to send ten NDAs to external reviewers and log links in Notion.

Commands

list /Contracts/2024
→ yields 10 fsids
share fsid_list ["111","112",..."120"] period 7 pwd nwy9

Returned

link: https://pan.baidu.com/s/1abcd1234
short_url: https://pan.baidu.com/s/1sXYz
pwd: nwy9
period: 7

The assistant formats the table in Markdown, which Notion paste converts to a database row set automatically.

5. Deep-Dive – How the Primitives Compose

“How do the atomic calls fit together, and what are the limits?”
Answer: Think of fsid as the primary key; every write operation consumes or produces fsids, and you can batch 10 items per call for meta, unlimited for copy/move/delete.

5.1 The fsid mental model

  • Each file or folder owns a unique fsid (uint64).
  • Paths can change; fsids stay constant during moves or renames.
  • Therefore store fsids in your app database if you plan to revisit the same item later.

5.2 Batching rules

Call Max items Notes
file_meta 10 fsids Use when you need size/md5 snapshot
copy/move/delete/rename no hard limit but keep JSON < 1 MB for safety
share 100 fsids beyond that create multiple links

5.3 Async vs sync

  • async = 0 – block until finished; simple, slower for >100 items.
  • async = 1 – server decides; usually finishes in seconds.
  • async = 2 – always returns immediately with taskid; suitable for thousands of files, yet task polling API is undocumented—avoid unless you can tolerate fire-and-forget.

Author’s reflection: For nightly backups I use async = 1; once I tried async = 2 and spent an hour guessing whether the task was done—turns out waiting blindly is more stressful than waiting synchronously.

5.4 Quota behaviour

get_quota returns:

{
  "total": 2147483648000,
  "used":  573440000000,
  "free":  1574043648000,
  "expire_soon": false
}

expire_soon is true when some promotional space will expire within seven days—handy for automated alerts.

6. First Errors You Will Meet – Quick Fix Sheet

“What are the first errors I will hit and how do I fix them?”
Answer: 400 usually means un-encoded Chinese path, 111 means expired token, and “tool not found” means you chose SSE for a local-upload action.

Symptom Root cause One-line fix
400 “path invalid” Chinese or space in path, not URL-encoded Encode slash AND characters
111 “access token invalid” Personal token refreshed Re-click the auth link
MCP client red badge Whitespace in token or wrong transport Trim token, restart client
“upload tool not found” SSE transport selected Switch to Python stdio
share 422 fsid_list typed as array instead of string Wrap JSON array in single quotes
taskid never completes async=2 with huge folder Chunk batch or use async=1

7. Action Checklist – Copy-Paste Ready

☐ Click personal-auth link → copy token
☐ Add "baidu-netdisk" MCP server block → green light
☐ Run user_info + get_quota → confirm numbers
☐ Create a test folder → list → rename → delete (smoke write)
☐ Upload one local file via stdio OR one URL via SSE
☐ Execute keyword search AND semantic search → compare speed
☐ Batch-share three files → import table into your KM system
☐ Schedule a cron / GitHub Action to do it nightly

8. One-Page Overview

Baidu Netdisk exposes an MCP server at https://mcp-pan.baidu.com/sse (and a stdio flavor for uploads).
After a two-minute OAuth hop you obtain an access token that lets any MCP-compatible client call:

  • list, meta, doc/image/video filters
  • make_dir, copy, move, delete, rename
  • three upload styles (local, URL, text)
  • keyword & semantic search
  • share-link generator with expiry & password
  • quota & user info

Local-file upload requires Python stdio; everything else works over SSE.
All write calls accept on-duplicate strategies and async flags; fsid is the durable identifier.
Typical tripping points are un-encoded paths, expired personal tokens, and trying to upload over SSE.
With the checklist above you can go from zero to automated cloud butler in ten minutes.

9. FAQ – Short Sentences, No Marketing

  1. Is there a rate limit?
    Not published for the experience tier; stay below 1 QPS and you will not notice.

  2. Can I upload a 50 GB Blu-ray image?
    Yes, but only through the stdio local-file tool and on a network that does not reset TCP sessions every hour.

  3. Does semantic search work inside PDF text?
    The input file states it returns abstract and content when available—if the PDF was OCR-ed by Baidu before, it will match.

  4. Are folders recursive in search?
    Both search types scan the chosen dir and its children.

  5. Can I rename a folder?
    Folders are files with category=6; use file_rename exactly like for files.

  6. What happens when the personal token expires during an async task?
    The task continues with the old token, but you need a fresh token to poll or start new tasks.

  7. Is HTTPS mandatory for URL uploads?
    The documentation says “publicly downloadable link,” HTTP included, but most users serve over HTTPS anyway.