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

Related MCP server: Synology MCP Server

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": "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

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