wd-mycloud-mcp

An MCP (Model Context Protocol) server that exposes Western Digital MyCloud Home file operations to AI assistants (Claude Desktop, etc.) — works both on local network and over the internet.

Features

• Browse, read, write, move, copy, delete files on WD MyCloud
• Three connection modes with automatic fallback:
  1. SMB (local network) — fastest, direct mount
  2. REST API (remote) — auto-login via WD cloud account, no browser needed
  3. SFTP — fallback when SSH is available
• Auto-mounts SMB share on first use (macOS)
• Token auto-refresh — stays logged in without manual intervention
• Path traversal protection on all operations
• File search by name query

Requirements

• macOS (uses mount_smbfs for SMB mode)
• Python 3.11+
• uv (recommended) or pip
• WD MyCloud Home device

Installation

git clone https://github.com/dy-le/wd-mycloud-mcp.git
cd wd-mycloud-mcp

# Install with uv
uv sync

# Or with pip
pip install -e .

Configuration

Environment variables

Variable	Default	Description
WD_MYCLOUD_HOST	MyCloud.local	Hostname or IP of device (use IP, not .local)
WD_MYCLOUD_SHARE	Public	SMB share name
WD_MYCLOUD_USER	guest	SMB username
WD_MYCLOUD_PASSWORD	(empty)	SMB password
WD_MYCLOUD_MOUNT	/Volumes/{SHARE}	Local SMB mount point
WD_MYCLOUD_CLOUD_EMAIL	(empty)	WD account email (for remote access)
WD_MYCLOUD_CLOUD_PASSWORD	(empty)	WD account password (for remote access)

Tip: Use the device's IP address for WD_MYCLOUD_HOST instead of the .local hostname to avoid mDNS resolution issues.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "wd-mycloud": {
      "command": "/path/to/.venv/bin/wd-mycloud-mcp",
      "env": {
        "WD_MYCLOUD_HOST": "192.168.1.100",
        "WD_MYCLOUD_SHARE": "YourShare",
        "WD_MYCLOUD_USER": "youruser",
        "WD_MYCLOUD_PASSWORD": "yourpass",
        "WD_MYCLOUD_MOUNT": "/Users/you/.wd-mycloud/mnt",
        "WD_MYCLOUD_CLOUD_EMAIL": "you@email.com",
        "WD_MYCLOUD_CLOUD_PASSWORD": "yourcloudpass"
      }
    }
  }
}

Remote access (away from home)

When not on the local network, the server automatically authenticates with the WD cloud service using WD_MYCLOUD_CLOUD_EMAIL and WD_MYCLOUD_CLOUD_PASSWORD. Tokens are cached at ~/.wd-mycloud/token.json and refreshed automatically before expiry.

If direct login is unavailable, you can install the included Chrome extension (chrome-extension/) to capture a token manually by visiting home.mycloud.com.

Available Tools

Tool	Description
list_directory(path)	List files and directories
read_file(path)	Read a text file
write_file(path, content)	Create or overwrite a text file
delete_file(path)	Delete a file
delete_directory(path, recursive)	Delete a directory
create_directory(path)	Create a directory
move(source, destination)	Move or rename
copy(source, destination)	Copy a file
search_files(query, path)	Search by filename
get_info(path)	Get file/directory metadata
connection_status()	Show current mode and auth status
login()	Force re-authentication

Release notes

v1.1.0

• Remote API mode: auto-login with WD cloud email/password, no Chrome extension required
• Token refresh: access tokens are refreshed automatically using stored refresh token
• Correct WD API endpoints sourced from open-source reference implementations:
  • File listing: GET /sdk/v2/filesSearch/parents?ids={parentId} (ids=root for root)
  • File download: GET /sdk/v3/files/{id}/content (v3 endpoint)
  • Delete: DELETE /sdk/v2/files/{id}
  • Move/rename: PATCH /sdk/v2/files/{id}
  • Create folder: POST /sdk/v2/files (multipart/related)
  • Write file: POST /sdk/v2/files/resumable (resumable upload)
• ID-based navigation with in-memory path→ID cache
• Auth0 config auto-discovered from https://config.mycloud.com/config/v1/config
• Fixed SMB: URL-encode credentials with special characters (e.g. @ in password)
• Fixed mount point: use user-owned path instead of /Volumes/ to avoid permission errors

v1.0.0

• Initial release: SMB-only local network access

Acknowledgements

This project references and was informed by the following open-source works:

• mnencia/mchfuse (Go) — correct Auth0 login flow (password-realm grant type), token refresh, file API paths (/v2/, /v3/), multipart/related upload format, and PATCH for move/rename
• sbencoding/WD-Bridge (Node.js) — filesSearch/parents?ids= parameter, ids=root for root listing, service URL discovery
• sbencoding/wdfs (C++) — device proxy URL discovery via device/v1/user/{sub}, remote access architecture
• everappz/MyCloudHomeSDKObjc (Objective-C) — complete API surface reference including resumable upload, token fields (id_token, access_token, refresh_token), and file metadata schema

License

Apache 2.0