Dropbox Manager

Manage Dropbox files securely with OAuth 2.0 PKCE via CLI or MCP server, supporting upload, download, search, delete, and account info operations.

Security Scan

The skill's documentation and manifest contain multiple mismatches (required credentials, install method, and MCP server configuration) and it relies on building or running external code that is not included in the package — proceed only after verifying the external repository and clarifying the inconsistencies.

Purpose & Capability

The declared registry metadata says no environment variables or credentials are required, but SKILL.json and SKILL.md clearly require Dropbox credentials (APP_KEY, APP_SECRET, ACCESS_TOKEN/REFRESH_TOKEN) to function. The package contains only docs (no executable code), yet the instructions require cloning and building an external repo (https://github.com/RyanLisse/Dropbook). These mismatches make it unclear what the skill actually needs and why the registry metadata says 'none'.

Instruction Scope

SKILL.md stays within Dropbox management functionality (OAuth, listing, upload, download). It does instruct the user/agent to clone and build an external repo, run an MCP server, and store tokens in macOS Keychain or a fallback file. It also recommends enabling project-level MCP servers (enableAllProjectMcpServers), which can cause agent tooling to automatically start servers — a configuration action with broader effects than simple API calls and worth caution.

Install Mechanism

There is no install spec in the registry package; instead the SKILL.md instructs cloning and building a GitHub repository. The references also suggest an alternative (an npx 'dbx-mcp-server') — two different install/runtime models are presented (native Swift binary vs node package). Relying on external code (not bundled) and offering multiple, inconsistent server implementations increases risk and user confusion.

Credentials

Access to Dropbox API keys/tokens is reasonable for a Dropbox manager, but the skill's manifests disagree about which variables are required: registry metadata says none, SKILL.json marks DROPBOX_APP_KEY, DROPBOX_APP_SECRET, and DROPBOX_ACCESS_TOKEN as required, SKILL.md describes OAuth with app key/secret and optional manual ACCESS_TOKEN, and references/mcp-setup.md expects a REFRESH_TOKEN for the npx server. This inconsistent list of required secrets is disproportionate and unclear. Also, tokens are saved to Keychain or to a plaintext fallback (~/.dropbook/auth.json), which is expected but should be explicit to a non-technical user.

Persistence & Privilege

The skill does not request always:true or other elevated platform privileges. It does instruct storing Dropbox tokens in the macOS Keychain (and a file fallback) and asks that project MCP servers be enabled in agent settings — both create persistent effects on the host. Autonomous invocation is allowed by default (disable-model-invocation: false), which combined with stored credentials could increase blast radius if the MCP server is enabled and launched automatically. This is expected for an agent-integrated MCP tool but worth explicit user consent.

What to consider before installing

This skill's docs and machine manifest disagree about what it needs and how to run it. Before installing or giving it credentials: 1) Verify and inspect the external repository (https://github.com/RyanLisse/Dropbook) — the package contains no code itself. 2) Confirm which environment variables the runtime actually requires (APP_KEY/SECRET, ACCESS_TOKEN, or REFRESH_TOKEN) and whether those are mandatory. 3) Prefer the OAuth Keychain flow (recommended) over dropping long-lived tokens in files or environment variables; if you must provide tokens, consider using least-privilege app scopes and a dedicated Dropbox app. 4) Avoid enabling 'enableAllProjectMcpServers' globally — only allow this MCP server after you trust and have tested the binary in a sandbox. 5) If anything is unclear, ask the publisher to reconcile SKILL.json, SKILL.md, and references/mcp-setup.md and to provide signed releases or a vetted distribution channel before running builds from source.

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

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

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)

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:

make logout
# or: swift run dropbook logout

MCP Server (Recommended)

Start the MCP server:

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:

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

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

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

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

{
  "deleted": true,
  "path": "/Docs/old-file.pdf"
}

get_account_info

Get Dropbox account information.

Parameters: None

Response:

{
  "name": "Ryan Lisse",
  "email": "[e-mail]"
}

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

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

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

{
  "enableAllProjectMcpServers": true
}

Claude Desktop

{
  "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 - a powerful cloud sync tool with native Dropbox support.

Install rclone

brew install rclone

Configure rclone for Dropbox

# 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

# 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

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

# 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
• CLAUDE.md - Full project documentation
• Dropbox API Docs
• rclone Dropbox Docs - Bulk sync and backup
• RFC 7636 - PKCE
• RFC 9700 - OAuth 2.0 Security Best Practices