Manage Dropbox files securely with OAuth 2.0 PKCE via CLI or MCP server, supporting upload, download, search, delete, and account info operations.
# Dropbox Manager Skill
Manage Dropbox files via MCP server and CLI. Swift-native implementation using SwiftyDropbox SDK with OAuth 2.0 PKCE and secure Keychain token storage.
## Setup
### Prerequisites
```bash
# Clone and build Dropbook
git clone https://github.com/RyanLisse/Dropbook.git
cd Dropbook
make build
```
### Authentication
#### Option 1: OAuth Login with Keychain (Recommended)
Use the interactive OAuth flow with secure Keychain storage:
```bash
export DROPBOX_APP_KEY="your_dropbox_app_key"
export DROPBOX_APP_SECRET="your_dropbox_app_secret"
make login
# or: swift run dropbook login
```
This will:
1. Generate PKCE code verifier and challenge (SHA256, RFC 7636)
2. Open an authorization URL with state parameter (CSRF protection)
3. Prompt you to paste the authorization code
4. Exchange code for access and refresh tokens
5. **Save tokens to macOS Keychain** (hardware-backed encryption)
6. Fall back to `~/.dropbook/auth.json` if Keychain unavailable
7. Enable automatic token refreshing
**Security Features (RFC 9700 compliant):**
- PKCE with S256 challenge method
- State parameter for CSRF protection
- Keychain storage with `kSecAttrAccessibleWhenUnlocked`
- CryptoKit for cryptographic operations
#### Option 2: Environment Variables (Legacy)
```bash
export DROPBOX_APP_KEY="your_dropbox_app_key"
export DROPBOX_APP_SECRET="your_dropbox_app_secret"
export DROPBOX_ACCESS_TOKEN="your_dropbox_access_token"
```
**Note**: Manual tokens don't support automatic refreshing. Use OAuth login for production use.
### Logout
Clear stored tokens from both Keychain and file storage:
```bash
make logout
# or: swift run dropbook logout
```
## MCP Server (Recommended)
Start the MCP server:
```bash
make mcp
# or: ./.build/debug/dropbook mcp
```
### MCP Tools
| Tool | Description |
|------|-------------|
| `list_directory` | List files and folders in a Dropbox directory |
| `search` | Search for files by name or content |
| `upload` | Upload a file to Dropbox |
| `download` | Download a file from Dropbox |
| `delete` | Delete a file or folder (moves to trash) |
| `get_account_info` | Get account name and email |
| `read_file` | Read contents of a text file |
#### list_directory
List files and folders in a Dropbox directory.
**Parameters:**
- `path` (string, optional): Directory path. Default: "/"
**Response:**
```json
{
"files": [
{"type": "file", "name": "doc.pdf", "path": "/Docs/doc.pdf", "size": 1024},
{"type": "folder", "name": "Projects", "path": "/Projects"}
]
}
```
#### search
Search for files by name or content.
**Parameters:**
- `query` (string, required): Search term
- `path` (string, optional): Path to search within. Default: "/"
**Response:**
```json
{
"count": 2,
"results": [
{"matchType": "filename", "metadata": {"name": "report.pdf", "path": "/Docs/report.pdf"}}
]
}
```
#### upload
Upload a file to Dropbox.
**Parameters:**
- `localPath` (string, required): Absolute path to local file
- `remotePath` (string, required): Destination in Dropbox
- `overwrite` (boolean, optional): Replace if exists. Default: false
**Response:**
```json
{
"uploaded": true,
"name": "file.txt",
"path": "/Uploads/file.txt",
"size": 5000
}
```
#### download
Download a file from Dropbox.
**Parameters:**
- `remotePath` (string, required): File path in Dropbox
- `localPath` (string, required): Local destination path
**Response:**
```json
{
"downloaded": true,
"to": "/tmp/report.pdf"
}
```
#### delete
Delete a file or folder from Dropbox (moves to trash).
**Parameters:**
- `path` (string, required): Path to delete in Dropbox
**Response:**
```json
{
"deleted": true,
"path": "/Docs/old-file.pdf"
}
```
#### get_account_info
Get Dropbox account information.
**Parameters:** None
**Response:**
```json
{
"name": "Ryan Lisse",
"email": "user@example.com"
}
```
#### read_file
Read and return the contents of a text file from Dropbox.
**Parameters:**
- `path` (string, required): Path to file in Dropbox
**Response:**
Returns the file contents as text. Only works with UTF-8 encoded text files.
## CLI Commands
```bash
# Authentication
make login # OAuth login with Keychain storage
make logout # Clear stored tokens
# File operations
make list # List root directory
swift run dropbook list /path
# Search files
swift run dropbook search "query" [path]
# Upload file
swift run dropbook upload /local/path /remote/path [--overwrite]
# Download file
swift run dropbook download /remote/path /local/path
# Start MCP server
make mcp
```
## MCP Client Configuration
### Claude Code (Project-level)
The project includes a `.mcp.json` file that configures the MCP server:
```json
{
"mcpServers": {
"dropbox": {
"command": "/path/to/Dropbook/.build/debug/dropbook",
"args": ["mcp"],
"env": {
"DROPBOX_APP_KEY": "${DROPBOX_APP_KEY}",
"DROPBOX_APP_SECRET": "${DROPBOX_APP_SECRET}"
}
}
}
}
```
Enable project MCP servers in Claude Code settings.json:
```json
{
"enableAllProjectMcpServers": true
}
```
### Claude Desktop
```json
{
"mcpServers": {
"dropbox": {
"command": "/path/to/dropbook/.build/debug/dropbook",
"args": ["mcp"],
"env": {
"DROPBOX_APP_KEY": "${DROPBOX_APP_KEY}",
"DROPBOX_APP_SECRET": "${DROPBOX_APP_SECRET}"
}
}
}
}
```
## Error Handling
| Error | Cause | Solution |
|-------|-------|----------|
| `notConfigured` | Missing env vars | Set DROPBOX_APP_KEY, DROPBOX_APP_SECRET |
| `invalidArguments` | Missing required params | Check tool parameters |
| `notFound` | Path doesn't exist | Use `list_directory` to verify paths |
| `itemNotFound` | No token in Keychain | Run `make login` to authenticate |
## Architecture
```
Dropbook/
├── Sources/
│ ├── DropbookCore/ # Business logic (actor-based)
│ │ ├── Auth/ # Keychain & file token storage
│ │ ├── Config/ # Configuration management
│ │ ├── Models/ # Domain models
│ │ └── Services/ # DropboxService actor
│ ├── DropbookCLI/ # CLI adapter
│ │ └── Commands/ # Login, logout, file commands
│ └── DropbookMCP/ # MCP server
├── dropbox-skill/ # Skill documentation
├── Makefile # Build automation
├── .mcp.json # MCP server configuration
└── Package.swift
```
## Bulk Operations with rclone
For large-scale operations like backups, syncing, or bulk transfers, use [rclone](https://rclone.org/) - a powerful cloud sync tool with native Dropbox support.
### Install rclone
```bash
brew install rclone
```
### Configure rclone for Dropbox
```bash
# Interactive setup (opens browser for OAuth)
rclone authorize dropbox
# Save the token output to config
mkdir -p ~/.config/rclone
cat > ~/.config/rclone/rclone.conf << 'EOF'
[dropbox]
type = dropbox
token = {"access_token":"...paste token here..."}
EOF
```
### Backup to Network Drive / Time Capsule
```bash
# Full backup with progress
rclone copy dropbox: /Volumes/TimeCapsule/Dropbox-Backup \
--progress \
--transfers 4 \
--checkers 8 \
--retries 10 \
--log-file /tmp/dropbox-backup.log
# Sync (mirror - deletes files not in source)
rclone sync dropbox: /Volumes/Backup/Dropbox --progress
# Check what would be copied (dry run)
rclone copy dropbox: /Volumes/Backup --dry-run
```
### Common rclone Commands
```bash
# List remote contents
rclone lsd dropbox: # List directories
rclone ls dropbox: # List all files
rclone size dropbox: # Calculate total size
# Copy operations
rclone copy dropbox:folder /local/path # Download folder
rclone copy /local/path dropbox:folder # Upload folder
# Sync (bidirectional)
rclone bisync dropbox: /local/path --resync
# Mount as filesystem (macOS - requires macFUSE)
rclone mount dropbox: /mnt/dropbox --vfs-cache-mode full
```
### rclone Flags for Reliability
| Flag | Description |
|------|-------------|
| `--progress` | Show real-time transfer progress |
| `--transfers 4` | Number of parallel transfers |
| `--checkers 8` | Number of parallel checkers |
| `--retries 10` | Retry failed operations |
| `--low-level-retries 20` | Retry low-level errors |
| `--log-file path` | Write logs to file |
| `--dry-run` | Show what would be done |
| `--checksum` | Verify with checksums |
### Rate Limiting
Dropbox has strict API rate limits. If you see `too_many_requests` errors:
```bash
# Use bandwidth limiting
rclone copy dropbox: /backup --bwlimit 1M
# Or add delays between operations
rclone copy dropbox: /backup --tpslimit 2
```
rclone handles rate limits automatically with exponential backoff.
## Best Practices
1. **Use OAuth login** - Secure Keychain storage with automatic token refresh
2. **Use MCP for agents** - More reliable for programmatic access
3. **Use rclone for bulk ops** - Better for backups and large transfers
4. **Validate paths first** - Use `list_directory` before operations
5. **Handle errors gracefully** - Check responses for error fields
6. **Respect rate limits** - Add delays between bulk operations
7. **Use absolute paths** - Always provide full paths for file operations
## Security
- **Keychain Storage**: Tokens stored with hardware-backed encryption
- **PKCE**: Proof Key for Code Exchange prevents authorization code interception
- **State Parameter**: CSRF protection for OAuth flow
- **Token Refresh**: Automatic refresh before expiration
- **CryptoKit**: Modern Swift cryptographic library
## Dependencies
- **SwiftyDropbox** (v10.2.4+): Official Dropbox Swift SDK
- **MCP (swift-sdk)**: Model Context Protocol SDK
- **CryptoKit**: Apple's cryptographic framework
- **rclone** (optional): For bulk operations and backups (`brew install rclone`)
## See Also
- [Dropbook GitHub](https://github.com/RyanLisse/Dropbook)
- [CLAUDE.md](../CLAUDE.md) - Full project documentation
- [Dropbox API Docs](https://www.dropbox.com/developers/documentation)
- [rclone Dropbox Docs](https://rclone.org/dropbox/) - Bulk sync and backup
- [RFC 7636 - PKCE](https://datatracker.ietf.org/doc/html/rfc7636)
- [RFC 9700 - OAuth 2.0 Security Best Practices](https://datatracker.ietf.org/doc/html/rfc9700)
don't have the plugin yet? install it then click "run inline in claude" again.
added explicit decision points for auth fallback, rate limiting, and file operation branches; clarified input requirements (env var names, scopes, system requirements); structured procedure into 8 discrete steps with clear inputs and outputs; documented all error codes and recovery paths; added edge cases (network timeouts, token expiration, empty results, non-utf8 files, relative path handling); preserved rclone guidance and security practices from original.
this skill manages files in Dropbox via a Swift CLI or MCP server, using OAuth 2.0 PKCE for secure authentication and macOS Keychain for token storage. use it when you need programmatic file operations (upload, download, search, delete, read), account info retrieval, or bulk sync tasks. best for agents and automation that require persistent, refreshable auth without manual token management.
Dropbox OAuth App:
DROPBOX_APP_KEY: OAuth app key from Dropbox App ConsoleDROPBOX_APP_SECRET: OAuth app secret (keep confidential, never commit)files.metadata.read, files.content.read, files.content.writemacOS Keychain (Recommended)
make login with hardware-backed encryptioncom.dropbook.authFile-based Fallback
~/.dropbook/auth.jsonEnvironment Variable (Legacy)
DROPBOX_ACCESS_TOKEN: Pre-generated access tokenoauth.dropboxapi.com and www.dropbox.comrclone binary (installed via brew install rclone)~/.config/rclone/rclone.conf with [dropbox] sectionInputs: git clone access, Xcode toolchain Process:
git clone https://github.com/RyanLisse/Dropbook.git
cd Dropbook
make build
Output: ./.build/debug/dropbook executable ready for use
Inputs: DROPBOX_APP_KEY, DROPBOX_APP_SECRET env vars
Process:
export DROPBOX_APP_KEY="your_app_key"
export DROPBOX_APP_SECRET="your_app_secret"
make login
During execution:
kSecAttrAccessibleWhenUnlocked~/.dropbook/auth.json unencrypted (warn user)Output: Tokens in Keychain or fallback file; ready for MCP/CLI use
Inputs: Auth from step 2, DROPBOX_APP_KEY (optional, for token refresh)
Process:
make mcp
# or: ./.build/debug/dropbook mcp
Server binds to stdio for MCP client communication (Claude Code, Claude Desktop).
Output: MCP server accepting tool calls on stdin/stdout
Inputs: Active MCP server, auth tokens, tool parameters
Each tool sends JSON-RPC request to server:
path (string, optional, default "/")files array (type, name, path, size for files)query (string, required), path (string, optional, default "/")count and results array (matchType, metadata)localPath (string, required, absolute path), remotePath (string, required), overwrite (boolean, optional, default false)uploaded (true/false), name, path, sizeremotePath (string, required), localPath (string, required)downloaded (true/false), to (destination path)path (string, required)deleted (true/false), pathname (string), email (string)path (string, required)Inputs: Auth from step 2, command arguments
swift run dropbook list [/path] # List directory
swift run dropbook search "query" [path] # Search files
swift run dropbook upload /local /remote [--overwrite]
swift run dropbook download /remote /local
swift run dropbook get-account-info # Account name/email
Output: CLI prints JSON or text to stdout
Inputs: Refresh token in Keychain or file Process: SDK automatically refreshes access token before expiration (if refresh token exists) Output: New access token stored in original location
Inputs: None Process:
make logout
Deletes tokens from both Keychain and ~/.dropbook/auth.json.
Output: All auth data removed; MCP/CLI no longer functional until re-login
Inputs: rclone installed, ~/.config/rclone/rclone.conf with Dropbox token
Process:
rclone copy dropbox: /Volumes/Backup --progress --transfers 4 --retries 10
rclone sync dropbox: /local/path --progress # Bidirectional
rclone size dropbox: # Check total size
Output: Files downloaded/uploaded with progress; logs at --log-file path
If Keychain available (default macOS path):
Else if Keychain unavailable or macOS < 12:
~/.dropbook/auth.jsonElse if user sets DROPBOX_ACCESS_TOKEN env var:
If overwrite=false and file exists at remotePath:
Else if overwrite=true:
If search query returns 0 results:
results array with count: 0If search path does not exist:
notFoundIf Dropbox API returns too_many_requests (429):
--bwlimit 1M or --tpslimit 2Else if retry count exhausted:
If request timeout (>30s) or connection refused:
Else if auth token expired and refresh token unavailable:
itemNotFound (token missing)make login againIf file is UTF-8 text:
Else if file is binary or non-UTF-8:
invalidFileType; use download tool insteadIf path is relative (e.g., docs/file.txt):
/docs/file.txt)Else if path contains invalid characters (null bytes, etc.):
invalidPathAll MCP tools return JSON objects with consistent structure:
Success:
{
"status": "success",
"<operation>": true,
...metadata...
}
Error:
{
"status": "error",
"error": "<error_code>",
"message": "<human_readable_message>"
}
| Code | Cause | Recovery |
|---|---|---|
notConfigured |
Missing DROPBOX_APP_KEY or DROPBOX_APP_SECRET |
Set env vars before make login |
invalidArguments |
Missing required tool parameter | Check MCP tool schema |
notFound |
Path does not exist in Dropbox | Use list_directory to verify |
itemNotFound |
No valid token in Keychain or file | Run make login |
accessDenied |
Token lacks required scope | Re-authorize with correct app |
conflict |
File exists, overwrite=false |
Set overwrite=true or choose different path |
invalidFileType |
read_file called on binary file |
Use download instead |
rateLimited |
Too many requests (429) | Wait and retry with backoff |
networkError |
Connection failed or timeout | Retry; check network |
invalidPath |
Path contains null bytes or invalid chars | Sanitize path |
localPath as specified; file permissions inherited from DropboxremotePath; file size and metadata in responsecom.dropbook.auth, Account dropbox-token~/.dropbook/auth.json (JSON with accessToken, refreshToken, expiresAt)~/.config/rclone/rclone.conf section [dropbox]Skill succeeded if:
Auth: make login completes and user sees "Logged in" message; tokens appear in Keychain (verify via security find-generic-password -s com.dropbook.auth)
MCP Server: make mcp starts without errors; Claude Code or Claude Desktop can call tools and receive JSON responses
File Operations: Tools return "status": "success" with correct metadata (file size, path, timestamp for uploads/downloads)
Search: Returns count > 0 with matching filenames in results
Account Info: Returns user's email and display name
Delete: File appears in Dropbox "Recently Deleted" folder
Token Refresh: After token expiration window, SDK automatically refreshes and subsequent API calls succeed without user re-login
CLI: swift run dropbook list outputs JSON directory listing
Bulk Sync: rclone completes with message "Transferred N files" and log file contains no error lines
Skill failed if:
make login returns notConfigured or invalidArguments (missing env vars)"status": "error"exit code 1 with too_many_requests after 10 retries