wd-mycloud-mcp

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