# wd-mycloud-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://docs.astral.sh/uv/) (recommended) or pip
- WD MyCloud Home device

## Installation

```bash
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`)

```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](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