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

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": "[email protected]",
        "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

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](https://github.com/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](https://github.com/sbencoding/WD-Bridge) (Node.js) — filesSearch/parents?ids= parameter, ids=root for root listing, service URL discovery
• [sbencoding/wdfs](https://github.com/sbencoding/wdfs) (C++) — device proxy URL discovery via device/v1/user/{sub}, remote access architecture
• [everappz/MyCloudHomeSDKObjc](https://github.com/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