dropbox-automation
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDropbox Automation via Rube MCP
通过Rube MCP实现Dropbox自动化
Automate Dropbox operations including file upload/download, search, folder management, sharing links, batch operations, and metadata retrieval through Composio's Dropbox toolkit.
借助Composio的Dropbox工具包,自动化Dropbox的各类操作,包括文件上传/下载、搜索、文件夹管理、共享链接、批量操作及元数据检索。
Prerequisites
前提条件
- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Dropbox connection via with toolkit
RUBE_MANAGE_CONNECTIONSdropbox - Always call first to get current tool schemas
RUBE_SEARCH_TOOLS
- 必须已连接Rube MCP(需具备RUBE_SEARCH_TOOLS权限)
- 通过使用
RUBE_MANAGE_CONNECTIONS工具包建立有效的Dropbox连接dropbox - 请始终先调用以获取最新的工具模式
RUBE_SEARCH_TOOLS
Setup
设置步骤
Get Rube MCP: Add as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
https://rube.app/mcp- Verify Rube MCP is available by confirming responds
RUBE_SEARCH_TOOLS - Call with toolkit
RUBE_MANAGE_CONNECTIONSdropbox - If connection is not ACTIVE, follow the returned auth link to complete Dropbox OAuth
- Confirm connection status shows ACTIVE before running any workflows
获取Rube MCP:在客户端配置中添加作为MCP服务器。无需API密钥 — 只需添加端点即可使用。
https://rube.app/mcp- 确认可正常响应,以此验证Rube MCP是否可用
RUBE_SEARCH_TOOLS - 调用并指定工具包为
RUBE_MANAGE_CONNECTIONSdropbox - 若连接状态未显示为ACTIVE,请按照返回的授权链接完成Dropbox OAuth认证
- 在运行任何工作流之前,确认连接状态为ACTIVE
Core Workflows
核心工作流
1. Search for Files and Folders
1. 搜索文件与文件夹
When to use: User wants to find files or folders by name, content, or type
Tool sequence:
- - Search by query string with optional path scope and filters [Required]
DROPBOX_SEARCH_FILE_OR_FOLDER - - Paginate through additional results using cursor [Required if has_more]
DROPBOX_SEARCH_CONTINUE - - Validate and get canonical path for a search result [Optional]
DROPBOX_GET_METADATA - - Read file content to verify it is the intended document [Optional]
DROPBOX_READ_FILE
Key parameters:
- : Search string (case-insensitive, 1+ non-whitespace characters)
query - : Scope search to a folder (e.g.,
options.path); empty string for root"/Documents" - : Filter by type (
options.file_categories,"image","document","pdf", etc.)"folder" - : Filter by extension (e.g.,
options.file_extensions)["jpg", "png"] - : Set
options.filename_onlyto match filenames only (not content)true - : Results per page (default 100, max 1000)
options.max_results
Pitfalls:
- Search returns with a
has_more: truewhen more results exist; MUST continue to avoid silently missing matchescursor - Maximum 10,000 matches total across all pages of search + search_continue
- returned
DROPBOX_GET_METADATAmay differ in casing from user input; always use the returned canonical pathpath_display - File content from may be returned as base64-encoded
DROPBOX_READ_FILE; decode before parsingfile_content_bytes
适用场景:用户希望按名称、内容或类型查找文件或文件夹
工具执行顺序:
- - 使用查询字符串进行搜索,可选择路径范围和筛选条件 [必填]
DROPBOX_SEARCH_FILE_OR_FOLDER - - 使用游标分页获取更多结果 [若存在has_more则必填]
DROPBOX_SEARCH_CONTINUE - - 验证搜索结果并获取其标准路径 [可选]
DROPBOX_GET_METADATA - - 读取文件内容以确认是否为目标文档 [可选]
DROPBOX_READ_FILE
关键参数:
- : 搜索字符串(不区分大小写,需包含1个以上非空白字符)
query - : 限定搜索范围至指定文件夹(例如
options.path);空字符串表示根目录"/Documents" - : 按类型筛选(
options.file_categories、"image"、"document"、"pdf"等)"folder" - : 按文件扩展名筛选(例如
options.file_extensions)["jpg", "png"] - : 设置为
options.filename_only仅匹配文件名(不包含内容)true - : 每页结果数量(默认100,最大1000)
options.max_results
注意事项:
- 当存在更多结果时,搜索会返回及对应的
has_more: true;必须调用续搜接口,避免遗漏结果cursor - 搜索及续搜操作的总匹配结果上限为10,000条
- 返回的
DROPBOX_GET_METADATA大小写可能与用户输入不同;请始终使用接口返回的标准路径path_display - 返回的文件内容可能为base64编码的
DROPBOX_READ_FILE;解析前需先解码file_content_bytes
2. Upload and Download Files
2. 文件上传与下载
When to use: User wants to upload files to Dropbox or download files from it
Tool sequence:
- - Upload a file to a specified path [Required for upload]
DROPBOX_UPLOAD_FILE - - Download/read a file from Dropbox [Required for download]
DROPBOX_READ_FILE - - Download an entire folder as a zip file [Optional]
DROPBOX_DOWNLOAD_ZIP - - Save a file from a public URL directly to Dropbox [Optional]
DROPBOX_SAVE_URL - - Download a file from a shared link URL [Optional]
DROPBOX_GET_SHARED_LINK_FILE - - Export non-downloadable files like Dropbox Paper to markdown/HTML [Optional]
DROPBOX_EXPORT_FILE
Key parameters:
- : Dropbox path (must start with
path, e.g.,/)"/Documents/report.pdf" - :
mode(default, fail on conflict) or"add"for uploads"overwrite" - :
autorenameto auto-rename on conflict instead of failingtrue - : FileUploadable object with
content,s3key, andmimetypefor uploadsname - : Public URL for
urlDROPBOX_SAVE_URL - :
export_format,"markdown", or"html"for Paper docs"plain_text"
Pitfalls:
- is asynchronous and may take up to 15 minutes for large files
DROPBOX_SAVE_URL - folder must be under 20 GB with no single file over 4 GB and fewer than 10,000 entries
DROPBOX_DOWNLOAD_ZIP - content may be base64-encoded; check response format
DROPBOX_READ_FILE - Shared link downloads via may require
DROPBOX_GET_SHARED_LINK_FILEfor protected linkslink_password
适用场景:用户需上传文件至Dropbox或从Dropbox下载文件
工具执行顺序:
- - 将文件上传至指定路径 [上传操作必填]
DROPBOX_UPLOAD_FILE - - 从Dropbox下载/读取文件 [下载操作必填]
DROPBOX_READ_FILE - - 将整个文件夹打包为ZIP文件下载 [可选]
DROPBOX_DOWNLOAD_ZIP - - 直接将公开URL中的文件保存至Dropbox [可选]
DROPBOX_SAVE_URL - - 从共享链接URL下载文件 [可选]
DROPBOX_GET_SHARED_LINK_FILE - - 将Dropbox Paper等无法直接下载的文件导出为markdown/HTML格式 [可选]
DROPBOX_EXPORT_FILE
关键参数:
- : Dropbox路径(必须以
path开头,例如/)"/Documents/report.pdf" - : 上传模式,
mode(默认,冲突时失败)或"add"(覆盖)"overwrite" - : 设置为
autorename时,冲突时自动重命名而非失败true - : 上传文件对象,包含
content、s3key和mimetype属性name - :
url使用的公开URLDROPBOX_SAVE_URL - : Paper文档导出格式,可选
export_format、"markdown"或"html""plain_text"
注意事项:
- 为异步操作,大文件可能需要长达15分钟处理时间
DROPBOX_SAVE_URL - 的目标文件夹需满足:大小不超过20GB,单个文件不超过4GB,条目数量少于10,000个
DROPBOX_DOWNLOAD_ZIP - 返回的内容可能为base64编码;请检查响应格式
DROPBOX_READ_FILE - 通过下载受保护的共享链接文件时,可能需要提供
DROPBOX_GET_SHARED_LINK_FILElink_password
3. Share Files and Manage Links
3. 文件共享与链接管理
When to use: User wants to create sharing links or manage existing shared links
Tool sequence:
- - Confirm file/folder exists and get canonical path [Prerequisite]
DROPBOX_GET_METADATA - - Check for existing shared links to avoid duplicates [Prerequisite]
DROPBOX_LIST_SHARED_LINKS - - Create a new shared link [Required]
DROPBOX_CREATE_SHARED_LINK - - Resolve a shared link URL to metadata [Optional]
DROPBOX_GET_SHARED_LINK_METADATA - - List all shared folders the user has access to [Optional]
DROPBOX_LIST_SHARED_FOLDERS
Key parameters:
- : File or folder path for link creation
path - :
settings.audience,"public", or"team""no_one" - :
settings.accessor"viewer""editor" - : ISO 8601 expiration date (e.g.,
settings.expires)"2026-12-31T23:59:59Z" - /
settings.require_password: Password protectionsettings.link_password - : Boolean for download permission
settings.allow_download - : For
direct_only, setLIST_SHARED_LINKSto only return direct links (not parent folder links)true
Pitfalls:
- fails with 409 Conflict if a shared link already exists for the path; check with
DROPBOX_CREATE_SHARED_LINKfirstDROPBOX_LIST_SHARED_LINKS - Always validate path with before creating links to avoid
DROPBOX_GET_METADATAerrorspath/not_found - Reuse existing links from instead of creating duplicates
DROPBOX_LIST_SHARED_LINKS - is deprecated; use
requested_visibilityfor newer implementationsaudience
适用场景:用户需创建共享链接或管理现有共享链接
工具执行顺序:
- - 确认文件/文件夹存在并获取标准路径 [前置操作]
DROPBOX_GET_METADATA - - 检查现有共享链接以避免重复创建 [前置操作]
DROPBOX_LIST_SHARED_LINKS - - 创建新的共享链接 [必填]
DROPBOX_CREATE_SHARED_LINK - - 将共享链接URL解析为元数据 [可选]
DROPBOX_GET_SHARED_LINK_METADATA - - 列出用户有权访问的所有共享文件夹 [可选]
DROPBOX_LIST_SHARED_FOLDERS
关键参数:
- : 创建链接的文件或文件夹路径
path - : 访问受众,可选
settings.audience、"public"或"team""no_one" - : 权限类型,可选
settings.access或"viewer""editor" - : ISO 8601格式的过期时间(例如
settings.expires)"2026-12-31T23:59:59Z" - /
settings.require_password: 设置密码保护settings.link_password - : 是否允许下载的布尔值
settings.allow_download - :
direct_only接口中设置为LIST_SHARED_LINKS时,仅返回直接链接(不包含父文件夹链接)true
注意事项:
- 若路径已存在共享链接,会返回409 Conflict错误;请先调用
DROPBOX_CREATE_SHARED_LINK检查DROPBOX_LIST_SHARED_LINKS - 创建链接前需始终通过验证路径,避免
DROPBOX_GET_METADATA错误path/not_found - 优先复用返回的现有链接,而非重复创建
DROPBOX_LIST_SHARED_LINKS - 已废弃;新版本请使用
requested_visibility参数audience
4. Manage Folders (Create, Move, Delete)
4. 文件夹管理(创建、移动、删除)
When to use: User wants to create, move, rename, or delete files and folders
Tool sequence:
- - Create a single folder [Required for create]
DROPBOX_CREATE_FOLDER - - Create multiple folders at once [Optional]
DROPBOX_CREATE_FOLDER_BATCH - - Move or rename a single file/folder [Required for move]
DROPBOX_MOVE_FILE_OR_FOLDER - - Move multiple items at once [Optional]
DROPBOX_MOVE_BATCH - - Delete a single file or folder [Required for delete]
DROPBOX_DELETE_FILE_OR_FOLDER - - Delete multiple items at once [Optional]
DROPBOX_DELETE_BATCH - - Copy a file or folder to a new location [Optional]
DROPBOX_COPY_FILE_OR_FOLDER - /
DROPBOX_CHECK_MOVE_BATCH- Poll async batch job status [Required for batch ops]DROPBOX_CHECK_FOLDER_BATCH
Key parameters:
- : Target path (must start with
path, case-sensitive)/ - /
from_path: Source and destination for move/copy operationsto_path - :
autorenameto auto-rename on conflicttrue - : Array of
entriesfor batch moves; array of paths for batch creates{from_path, to_path} - : Set
allow_shared_folderto allow moving shared folderstrue - : Set
allow_ownership_transferif move changes ownershiptrue
Pitfalls:
- All paths are case-sensitive and must start with
/ - Paths must NOT end with or whitespace
/ - Batch operations may be asynchronous; poll with or
DROPBOX_CHECK_MOVE_BATCHDROPBOX_CHECK_FOLDER_BATCH - (v1) has "all or nothing" behavior - if any entry fails, entire batch fails
DROPBOX_FILES_MOVE_BATCH - (v2) is preferred over
DROPBOX_MOVE_BATCH(v1)DROPBOX_FILES_MOVE_BATCH - Maximum 1000 entries per batch delete/move; 10,000 paths per batch folder create
- Case-only renaming is not supported in batch move operations
适用场景:用户需创建、移动、重命名或删除文件及文件夹
工具执行顺序:
- - 创建单个文件夹 [创建操作必填]
DROPBOX_CREATE_FOLDER - - 批量创建多个文件夹 [可选]
DROPBOX_CREATE_FOLDER_BATCH - - 移动或重命名单个文件/文件夹 [移动操作必填]
DROPBOX_MOVE_FILE_OR_FOLDER - - 批量移动多个条目 [可选]
DROPBOX_MOVE_BATCH - - 删除单个文件或文件夹 [删除操作必填]
DROPBOX_DELETE_FILE_OR_FOLDER - - 批量删除多个条目 [可选]
DROPBOX_DELETE_BATCH - - 将文件或文件夹复制至新位置 [可选]
DROPBOX_COPY_FILE_OR_FOLDER - /
DROPBOX_CHECK_MOVE_BATCH- 轮询异步批量任务状态 [批量操作必填]DROPBOX_CHECK_FOLDER_BATCH
关键参数:
- : 目标路径(必须以
path开头,区分大小写)/ - /
from_path: 移动/复制操作的源路径和目标路径to_path - : 设置为
autorename时,冲突时自动重命名true - : 批量移动的条目数组(每个元素为
entries);批量创建的路径数组{from_path, to_path} - : 设置为
allow_shared_folder时,允许移动共享文件夹true - : 设置为
allow_ownership_transfer时,允许移动操作变更所有权true
注意事项:
- 所有路径区分大小写且必须以开头
/ - 路径不能以或空白字符结尾
/ - 批量操作可能为异步;需通过或
DROPBOX_CHECK_MOVE_BATCH轮询状态DROPBOX_CHECK_FOLDER_BATCH - 旧版(v1)为“全有或全无”模式 — 若任意条目失败,整个批量任务失败
DROPBOX_FILES_MOVE_BATCH - 推荐使用新版(v2)替代旧版
DROPBOX_MOVE_BATCH(v1)DROPBOX_FILES_MOVE_BATCH - 批量删除/移动的条目上限为1000个;批量创建文件夹的路径上限为10,000个
- 批量移动操作不支持仅修改大小写的重命名
5. List Folder Contents
5. 列出文件夹内容
When to use: User wants to browse or enumerate files in a Dropbox folder
Tool sequence:
- - List contents of a folder [Required]
DROPBOX_LIST_FILES_IN_FOLDER - - Alternative folder listing with deleted entries support [Optional]
DROPBOX_LIST_FOLDERS - - Get details for a specific item [Optional]
DROPBOX_GET_METADATA
Key parameters:
- : Folder path (empty string
pathfor root)"" - :
recursiveto list all nested contentstrue - : Max results per request (default/max 2000)
limit - :
include_deletedto include deleted but recoverable itemstrue - :
include_media_infoto get photo/video metadatatrue
Pitfalls:
- Use empty string for root folder, not
"""/" - Recursive listings can be very large; use to control page size
limit - Results may paginate via cursor even with small limits
- returns 409 Conflict with
DROPBOX_LIST_FILES_IN_FOLDERfor incorrect pathspath/not_found
适用场景:用户需浏览或枚举Dropbox文件夹中的文件
工具执行顺序:
- - 列出文件夹内容 [必填]
DROPBOX_LIST_FILES_IN_FOLDER - - 支持已删除条目的文件夹列表接口 [可选]
DROPBOX_LIST_FOLDERS - - 获取特定条目的详细信息 [可选]
DROPBOX_GET_METADATA
关键参数:
- : 文件夹路径(空字符串
path表示根目录)"" - : 设置为
recursive时,列出所有嵌套内容true - : 单次请求的最大结果数(默认/上限为2000)
limit - : 设置为
include_deleted时,包含已删除但可恢复的条目true - : 设置为
include_media_info时,获取照片/视频的元数据true
注意事项:
- 根目录请使用空字符串,而非
"""/" - 递归列出的内容可能非常多;使用参数控制每页大小
limit - 即使限制了小结果数,仍可能通过游标分页返回结果
- 路径错误时,会返回409 Conflict及
DROPBOX_LIST_FILES_IN_FOLDER错误path/not_found
Common Patterns
通用模式
ID Resolution
ID解析
- Path-based: Most Dropbox tools use path strings (e.g., )
"/Documents/file.pdf" - ID-based: Some tools accept format (e.g.,
id:...)"id:4g0reWVRsAAAAAAAAAAAQ" - Canonical path: Always use or
path_displayfrompath_lowerresponses for subsequent callsDROPBOX_GET_METADATA - Shared link URL: Use to resolve URLs to paths/IDs
DROPBOX_GET_SHARED_LINK_METADATA
- 基于路径: 大多数Dropbox工具使用路径字符串(例如)
"/Documents/file.pdf" - 基于ID: 部分工具接受格式的参数(例如
id:...)"id:4g0reWVRsAAAAAAAAAAAQ" - 标准路径: 后续操作请始终使用返回的
DROPBOX_GET_METADATA或path_displaypath_lower - 共享链接URL: 使用将URL解析为路径/ID
DROPBOX_GET_SHARED_LINK_METADATA
Pagination
分页
Dropbox uses cursor-based pagination across most endpoints:
- Search: Follow +
has_morewithcursor(max 10,000 total matches)DROPBOX_SEARCH_CONTINUE - Folder listing: Follow cursor from response until no more pages
- Shared links: Follow +
has_moreincursorDROPBOX_LIST_SHARED_LINKS - Batch job status: Poll with /
DROPBOX_CHECK_MOVE_BATCHDROPBOX_CHECK_FOLDER_BATCH
Dropbox多数接口采用基于游标的分页机制:
- 搜索: 当返回时,使用
has_more调用cursor(总匹配结果上限10,000条)DROPBOX_SEARCH_CONTINUE - 文件夹列表: 跟随响应中的游标直到无更多结果
- 共享链接: 当返回
DROPBOX_LIST_SHARED_LINKS时,使用has_more续取cursor - 批量任务状态: 通过/
DROPBOX_CHECK_MOVE_BATCH轮询DROPBOX_CHECK_FOLDER_BATCH
Async Operations
异步操作
Several Dropbox operations run asynchronously:
- - returns job ID; poll or set
DROPBOX_SAVE_URL(up to 120s default)wait: true - /
DROPBOX_MOVE_BATCH- may return job IDDROPBOX_FILES_MOVE_BATCH - - may return job ID
DROPBOX_CREATE_FOLDER_BATCH - - returns job ID
DROPBOX_DELETE_BATCH
部分Dropbox操作为异步执行:
- - 返回任务ID;可轮询或设置
DROPBOX_SAVE_URL(默认超时120秒)wait: true - /
DROPBOX_MOVE_BATCH- 可能返回任务IDDROPBOX_FILES_MOVE_BATCH - - 可能返回任务ID
DROPBOX_CREATE_FOLDER_BATCH - - 返回任务ID
DROPBOX_DELETE_BATCH
Known Pitfalls
已知注意事项
Path Formats
路径格式
- All paths must start with (except empty string for root in some endpoints)
/ - Paths must NOT end with or contain trailing whitespace
/ - Paths are case-sensitive for write operations
- from API may differ in casing from user input; always prefer API-returned paths
path_display
- 所有路径必须以开头(部分接口的根目录除外,使用空字符串)
/ - 路径不能以或空白字符结尾
/ - 写入操作的路径区分大小写
- API返回的大小写可能与用户输入不同;请优先使用API返回的路径
path_display
Rate Limits
速率限制
- Dropbox API has per-endpoint rate limits; batch operations help reduce call count
- Search is limited to 10,000 total matches across all pagination
- has a 15-minute timeout for large files
DROPBOX_SAVE_URL
- Dropbox API对各接口有速率限制;批量操作可减少调用次数
- 搜索操作的总匹配结果上限为10,000条
- 处理大文件的超时时间为15分钟
DROPBOX_SAVE_URL
File Content
文件内容
- may return content as base64-encoded
DROPBOX_READ_FILEfile_content_bytes - Non-downloadable files (Dropbox Paper, Google Docs) require instead
DROPBOX_EXPORT_FILE - Download URLs from shared links require proper authentication headers
- 返回的内容可能为base64编码的
DROPBOX_READ_FILEfile_content_bytes - Dropbox Paper、Google Docs等无法直接下载的文件,需使用导出
DROPBOX_EXPORT_FILE - 共享链接的下载URL需要正确的认证头
Sharing
共享功能
- Creating a shared link when one already exists returns a 409 Conflict error
- Always check before creating new links
DROPBOX_LIST_SHARED_LINKS - Shared folder access may not appear in standard path listings; use
DROPBOX_LIST_SHARED_FOLDERS
- 若路径已存在共享链接,会返回409 Conflict错误
DROPBOX_CREATE_SHARED_LINK - 创建新链接前请始终调用检查
DROPBOX_LIST_SHARED_LINKS - 共享文件夹的内容可能不会出现在标准路径列表中;请使用查询
DROPBOX_LIST_SHARED_FOLDERS
Quick Reference
快速参考
| Task | Tool Slug | Key Params |
|---|---|---|
| Search files | | |
| Continue search | | |
| List folder | | |
| List folders | | |
| Get metadata | | |
| Read/download file | | |
| Upload file | | |
| Save URL to Dropbox | | |
| Download folder zip | | |
| Export Paper doc | | |
| Download shared link | | |
| Create shared link | | |
| List shared links | | |
| Shared link metadata | | |
| List shared folders | | |
| Create folder | | |
| Create folders batch | | |
| Move file/folder | | |
| Move batch | | |
| Delete file/folder | | |
| Delete batch | | |
| Copy file/folder | | |
| Check batch status | | |
| 任务 | 工具标识 | 关键参数 |
|---|---|---|
| 搜索文件 | | |
| 续搜结果 | | |
| 列出文件夹内容 | | |
| 列出文件夹 | | |
| 获取元数据 | | |
| 读取/下载文件 | | |
| 上传文件 | | |
| URL保存至Dropbox | | |
| 下载文件夹ZIP | | |
| 导出Paper文档 | | |
| 下载共享链接文件 | | |
| 创建共享链接 | | |
| 列出共享链接 | | |
| 共享链接元数据 | | |
| 列出共享文件夹 | | |
| 创建文件夹 | | |
| 批量创建文件夹 | | |
| 移动文件/文件夹 | | |
| 批量移动 | | |
| 删除文件/文件夹 | | |
| 批量删除 | | |
| 复制文件/文件夹 | | |
| 检查批量任务状态 | | |