dropbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Dropbox

Tools for working with files and folders in Dropbox — upload and write files, organize (move/copy/delete/create folders), navigate and search, read file contents, create and modify shared links, manage shared-folder membership, and create file requests. Wraps the Dropbox API v2 (

https://api.dropboxapi.com/2/<namespace>/<method>

, with uploads/downloads on

https://content.dropboxapi.com

). Read-only tools are clearly marked; write tools return clean file/folder metadata rather than silently attaching links or contents.

Independent, unofficial connector for Dropbox. Not affiliated with, endorsed by, or sponsored by Dropbox. "Dropbox" is a trademark of its owner, used only to identify the service this connector works with.

用于在Dropbox中处理文件和文件夹的工具——支持上传和写入文件、整理（移动/复制/删除/创建文件夹）、导航与搜索、读取文件内容、创建和修改共享链接、管理共享文件夹成员以及创建文件请求。封装了Dropbox API v2（接口地址为

https://api.dropboxapi.com/2/<namespace>/<method>

，上传/下载操作使用

https://content.dropboxapi.com

）。只读工具会被明确标记；写入工具会返回清晰的文件/文件夹元数据，而非静默附加链接或内容。

这是独立的非官方Dropbox连接器，与Dropbox无关联、未获其认可或赞助。“Dropbox”是其所有者的商标，仅用于标识本连接器所适配的服务。

When to use this

适用场景

An agent needs to save, move, copy, rename, or delete files and folders in Dropbox.
An agent needs to find a file or folder (by name or content) or list a folder's contents before acting on it.
An agent needs to read a text file's contents inline, or hand off a file's bytes via a temporary or durable link.
An agent needs to share a file/folder, change link settings, or manage who can access a shared folder.

Agent需要在Dropbox中保存、移动、复制、重命名或删除文件和文件夹时。
Agent需要查找文件或文件夹（按名称或内容），或在操作前列出文件夹内容时。
Agent需要直接读取文本文件内容，或通过临时或持久化链接传递文件字节时。
Agent需要共享文件/文件夹、修改链接设置，或管理共享文件夹的访问人员时。

Setup

设置步骤

This is an agentskills.io skill.

If the connector has not been installed as a skill yet, install it first with

npx skills add zapier/connectors --skill dropbox

(or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or

zapier-sdk

auth commands, run

npm install --omit=dev

here once. Importing the published package as a dependency in your own project instead? That

npm install

already resolves everything — see

references/use-as-sdk.md

The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:

You have...	Load
An MCP-aware client — tools may already be loaded (e.g. `mcp__dropbox__<tool>` ), or you can register a local server yourself (or guide the user to)	`references/use-as-mcp.md`
Terminal / subprocess access (you can run `node` )	`references/use-as-cli.md`
Only your own code, importing this package as a dependency	`references/use-as-sdk.md`
No tool access, no terminal, no ability to import this package — you write your own code that calls the Dropbox API directly (e.g. a code-execution sandbox)	`references/use-as-recipe.md`

这是一款agentskills.io技能。

如果该连接器尚未作为技能安装，请先使用

npx skills add zapier/connectors --skill dropbox

（或你的工具链自带的技能安装机制）进行安装，然后继续后续操作。安装技能会复制这些文件，但不会安装依赖项。运行CLI、本地MCP服务器或

zapier-sdk

认证命令前，请先在此处执行一次

npm install --omit=dev

。如果是在你自己的项目中导入已发布的包作为依赖？那

npm install

已经解决了所有依赖问题——请查看

references/use-as-sdk.md

。

该连接器运行于**Node.js 22.18+**环境。请根据你的运行方式选择对应的参考文档，并在进行任何操作前加载它：

你的环境...	加载文档
支持MCP的客户端——工具可能已加载（例如 `mcp__dropbox__<tool>` ），你也可以自行注册本地服务器（或引导用户注册）	`references/use-as-mcp.md`
拥有终端/子进程访问权限（可以运行 `node` 命令）	`references/use-as-cli.md`
仅使用自有代码，将此包作为依赖导入	`references/use-as-sdk.md`
无工具访问权限、无终端、无法导入此包——你需要编写自己的代码直接调用Dropbox API（例如代码执行沙箱）	`references/use-as-recipe.md`

Scripts

脚本

All 21 scripts use the single

dropbox

connection. Each script's

inputSchema

outputSchema

(Zod) inside the script file is the source of truth for its contract.

Script	Script name	Connections	Description
`scripts/uploadFile.ts`	`uploadFile`	Single ( `dropbox` )	Upload a file by fetching its bytes from a URL (chunked session for large files).
`scripts/createTextFile.ts`	`createTextFile`	Single ( `dropbox` )	Create or overwrite a file from plain text content.
`scripts/appendToTextFile.ts`	`appendToTextFile`	Single ( `dropbox` )	Append text to a text file (creates it if absent).
`scripts/createFolder.ts`	`createFolder`	Single ( `dropbox` )	Create a folder at a path.
`scripts/moveFile.ts`	`moveFile`	Single ( `dropbox` )	Move or rename a file or folder.
`scripts/copyFile.ts`	`copyFile`	Single ( `dropbox` )	Copy a file or folder to a new path.
`scripts/deletePath.ts`	`deletePath`	Single ( `dropbox` )	Delete a file or folder (recoverable for a limited time).
`scripts/listFolder.ts`	`listFolder`	Single ( `dropbox` )	List a folder's immediate contents (cursor-paged).
`scripts/searchFiles.ts`	`searchFiles`	Single ( `dropbox` )	Search files/folders by name or content (cursor-paged).
`scripts/getFileMetadata.ts`	`getFileMetadata`	Single ( `dropbox` )	Get metadata for one file or folder by path or id.
`scripts/getTemporaryLink.ts`	`getTemporaryLink`	Single ( `dropbox` )	Get a ~4h direct download URL for a file.
`scripts/getFileContents.ts`	`getFileContents`	Single ( `dropbox` )	Read a text file's inline content (UTF-8, size-capped).
`scripts/createSharedLink.ts`	`createSharedLink`	Single ( `dropbox` )	Create a durable shareable link (returns the existing one if present).
`scripts/modifySharedLinkSettings.ts`	`modifySharedLinkSettings`	Single ( `dropbox` )	Change an existing shared link's settings. Resolve `url` via `listSharedLinks` .
`scripts/listSharedLinks.ts`	`listSharedLinks`	Single ( `dropbox` )	List existing shared links, optionally for a path.
`scripts/listSharedFolders.ts`	`listSharedFolders`	Single ( `dropbox` )	List shared folders the account belongs to (resolver for `shared_folder_id` ).
`scripts/addFolderMember.ts`	`addFolderMember`	Single ( `dropbox` )	Add members (by email) to a shared folder. Resolve `shared_folder_id` via `listSharedFolders` .
`scripts/removeFolderMember.ts`	`removeFolderMember`	Single ( `dropbox` )	Remove a member from a shared folder (polls to completion).
`scripts/createFileRequest.ts`	`createFileRequest`	Single ( `dropbox` )	Create a public upload page into a folder.
`scripts/listFileRequests.ts`	`listFileRequests`	Single ( `dropbox` )	List the account's file requests.
`scripts/getCurrentAccount.ts`	`getCurrentAccount`	Single ( `dropbox` )	Identify the account and its team/personal namespace ids.

Several scripts take an id or url best resolved from another script — those resolution hints are in the field descriptions (e.g.

addFolderMember.shared_folder_id

←

listSharedFolders

;

modifySharedLinkSettings.url

←

listSharedLinks

所有21个脚本均使用单一的

dropbox

连接。每个脚本文件内的

inputSchema

outputSchema

（基于Zod）是其契约的权威来源。

脚本	脚本名称	连接方式	描述
`scripts/uploadFile.ts`	`uploadFile`	单一连接( `dropbox` )	通过URL获取文件字节进行上传（大文件使用分块会话）。
`scripts/createTextFile.ts`	`createTextFile`	单一连接( `dropbox` )	从纯文本内容创建或覆盖文件。
`scripts/appendToTextFile.ts`	`appendToTextFile`	单一连接( `dropbox` )	向文本文件追加内容（文件不存在则创建）。
`scripts/createFolder.ts`	`createFolder`	单一连接( `dropbox` )	在指定路径创建文件夹。
`scripts/moveFile.ts`	`moveFile`	单一连接( `dropbox` )	移动或重命名文件或文件夹。
`scripts/copyFile.ts`	`copyFile`	单一连接( `dropbox` )	将文件或文件夹复制到新路径。
`scripts/deletePath.ts`	`deletePath`	单一连接( `dropbox` )	删除文件或文件夹（可在有限时间内恢复）。
`scripts/listFolder.ts`	`listFolder`	单一连接( `dropbox` )	列出文件夹的直接内容（基于游标分页）。
`scripts/searchFiles.ts`	`searchFiles`	单一连接( `dropbox` )	按名称或内容搜索文件/文件夹（基于游标分页）。
`scripts/getFileMetadata.ts`	`getFileMetadata`	单一连接( `dropbox` )	通过路径或ID获取单个文件或文件夹的元数据。
`scripts/getTemporaryLink.ts`	`getTemporaryLink`	单一连接( `dropbox` )	获取文件的临时直接下载链接（有效期约4小时）。
`scripts/getFileContents.ts`	`getFileContents`	单一连接( `dropbox` )	直接读取文本文件内容（UTF-8编码，有大小限制）。
`scripts/createSharedLink.ts`	`createSharedLink`	单一连接( `dropbox` )	创建持久化共享链接（若已存在则返回现有链接）。
`scripts/modifySharedLinkSettings.ts`	`modifySharedLinkSettings`	单一连接( `dropbox` )	修改现有共享链接的设置。需通过 `listSharedLinks` 解析 `url` 参数。
`scripts/listSharedLinks.ts`	`listSharedLinks`	单一连接( `dropbox` )	列出现有共享链接，可指定路径筛选。
`scripts/listSharedFolders.ts`	`listSharedFolders`	单一连接( `dropbox` )	列出账户所属的共享文件夹（用于解析 `shared_folder_id` ）。
`scripts/addFolderMember.ts`	`addFolderMember`	单一连接( `dropbox` )	向共享文件夹添加成员（通过邮箱）。需通过 `listSharedFolders` 解析 `shared_folder_id` 。
`scripts/removeFolderMember.ts`	`removeFolderMember`	单一连接( `dropbox` )	从共享文件夹移除成员（轮询直至完成）。
`scripts/createFileRequest.ts`	`createFileRequest`	单一连接( `dropbox` )	创建指向文件夹的公共上传页面。
`scripts/listFileRequests.ts`	`listFileRequests`	单一连接( `dropbox` )	列出账户的文件请求。
`scripts/getCurrentAccount.ts`	`getCurrentAccount`	单一连接( `dropbox` )	识别账户及其团队/个人命名空间ID。

部分脚本需要的ID或URL最好通过其他脚本解析获取——这些解析提示会在字段描述中说明（例如

addFolderMember.shared_folder_id

←

listSharedFolders

；

modifySharedLinkSettings.url

←

listSharedLinks

）。

Disambiguation & refusals

歧义处理与拒绝规则

Disambiguating items by name. Dropbox addresses items by path or id, and paths are case-insensitive — two items can look like the same name. Before writing to (move/copy/delete/share) an item the user named in words rather than by exact path, resolve it first with

searchFiles

listFolder

Exactly one match → act on it; don't over-confirm.
Two or more matches that tie (e.g.
```
report.pdf
```
in two different folders, or a shared-folder name that collides) → stop, list the candidates with a distinguishing field (full
```
path_display
```
, or
```
shared_folder_id
```
for folders), and ask which one. Never silently pick.

The entity types most likely to collide here are files/folders by name (resolve via

searchFiles

listFolder

, disambiguate on

path_display

) and shared folders by name (resolve via

listSharedFolders

, disambiguate on

shared_folder_id

Operations this connector does NOT perform — say so, don't fake it. If the user asks for one of these, tell them it's unsupported rather than substituting a different tool and reporting success:

Bulk/batch moves, copies, or deletes in one call. There is no batch tool — loop the single-item tools (
```
moveFile
```
/
```
copyFile
```
/
```
deletePath
```
) yourself, or tell the user it'll be one call per item.
Reading binary documents (PDF/image/Office) as text, OCR, or document parsing.
```
getFileContents
```
returns UTF-8 text only; for other files it returns
```
is_text:false
```
and you must hand off the bytes via
```
getTemporaryLink
```
. Don't claim to have read a PDF's contents.
Fetching or editing an individual file request, or sharing a whole folder as a managed share. Only
```
createFileRequest
```
+
```
listFileRequests
```
are available; there is no get/update file-request or
```
shareFolder
```
tool.

按名称区分项目。Dropbox通过路径或ID定位项目，且路径不区分大小写——两个项目可能名称看起来相同。在对用户用文字命名而非精确路径指定的项目执行写入操作（移动/复制/删除/共享）前，需先通过

searchFiles

或

listFolder

解析：

唯一匹配项 → 直接操作；无需额外确认。
多个匹配项冲突（例如两个不同文件夹中的
```
report.pdf
```
，或共享文件夹名称冲突）→ 停止操作，列出候选项目并附上区分字段（完整
```
path_display
```
或文件夹的
```
shared_folder_id
```
），询问用户选择哪一个。绝不能静默选择。

最容易发生冲突的实体类型是按名称区分的文件/文件夹（通过

searchFiles

listFolder

解析，用

path_display

区分）和按名称区分的共享文件夹（通过

listSharedFolders

解析，用

shared_folder_id

区分）。

本连接器不支持的操作——直接说明，不要伪造功能。如果用户请求以下操作，请告知用户不支持，而非替换为其他工具并报告成功：

批量移动、复制或删除操作。本连接器没有批量工具——请自行循环调用单项目工具（
```
moveFile
```
/
```
copyFile
```
/
```
deletePath
```
），或告知用户需要逐个调用。
将二进制文档（PDF/图片/Office文件）读取为文本、OCR识别或文档解析。
```
getFileContents
```
仅返回UTF-8文本；对于其他文件，会返回
```
is_text:false
```
，你必须通过
```
getTemporaryLink
```
传递字节数据。不要声称已读取PDF内容。
获取或编辑单个文件请求，或作为托管共享共享整个文件夹。仅支持
```
createFileRequest
```
+
```
listFileRequests
```
；没有获取/更新文件请求或
```
shareFolder
```
工具。

Auth

认证

Every shape passes auth as one connection selector, not the secret — a

[<resolver>:]<value>

string. Every connector accepts

zapier:<connection-id>

(Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The

<resolver>:

prefix is optional; a bare value goes to the first resolver that claims it — a UUID-shaped bare value always claims

zapier:

. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.

Checking what's already configured first? Don't dump environment values to do it —

env

env | grep <name>

prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (

env | cut -d= -f1 | grep -i <name>

) or test a known name directly (

[ -n "$VAR_NAME" ]

No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:

	Load
Pass the credential directly	`references/use-without-zapier.md`
Route it through a Zapier connection	`references/use-with-zapier.md`

每个操作都通过一个连接选择器传递认证信息，而非密钥——格式为

[<resolver>:]<value>

的字符串。每个连接器都接受

zapier:<connection-id>

（Zapier托管的认证——通过Zapier的认证、重试和治理层路由）；部分连接器还接受一种或多种直接令牌解析器（名称和数量因连接器而异）——请查看本连接器的解析器列表，不要假设。

<resolver>:

前缀是可选的；纯值会交给第一个声明支持它的解析器——UUID格式的纯值默认使用

zapier:

解析器。每个脚本都会声明它所需的连接以及接受的解析器。传递连接的确切语法（以及查看本连接器解析器列表的方式）因运行环境而异——请查看你之前加载的参考文档。

想要先查看已配置的内容？不要直接打印环境变量——

env

或

env | grep <name>

会同时打印名称和值，如果设置了有效凭据，会将其泄露到日志中。请仅查看名称（

env | cut -d= -f1 | grep -i <name>

）或直接测试已知名称（

[ -n "$VAR_NAME" ]

）。

还没有连接？请选择一种方式——并按照参考文档的流程获取连接；不要直接向用户索要连接ID或令牌，仿佛他们已经记住了这些信息：

	加载文档
直接传递凭据	`references/use-without-zapier.md`
通过Zapier连接路由	`references/use-with-zapier.md`

Output format

输出格式

Every script returns a

{ data, meta }

envelope:

data
— the script's result (the shape its
```
outputSchema
```
declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
meta.outputDataValidation
— what validating
```
data
```
did:
- ```
{ skipped: false, droppedPaths: null }
```
  — validated, nothing removed.
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  — validated, but those paths were stripped from
```
data
```
  : fields the script returned from the API that the
```
outputSchema
```
  doesn't declare. If you need them, re-run with output validation skipped.
- ```
{ skipped: true }
```
  — validation was bypassed;
```
data
```
  is the raw, unchecked script output.

Reading dropped fields /
skipOutputDataValidation
. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.

Trimming the result /
filterOutputData
. To shrink a large result down to the fields you need, pass a jq expression that post-processes

data

(again, exact syntax per shape). The jq runs against

data

only, NOT the

{ data, meta }

envelope, so write it rooted at

data

(run the script's

--help

— or your shape's equivalent — to see its output schema). The transformed value replaces

data

meta

is preserved, and the result is NOT re-validated against the output schema.

每个脚本都会返回

{ data, meta }

格式的结果包：

data
—— 脚本的执行结果（其
```
outputSchema
```
声明的结构；请查看你加载的参考文档，了解如何在你的环境中查看脚本的确切模式）。
meta.outputDataValidation
—— 对
```
data
```
的验证情况：
- ```
{ skipped: false, droppedPaths: null }
```
  —— 已验证，未移除任何内容。
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  —— 已验证，但这些路径已从
```
data
```
  中移除：脚本从API返回的字段未在
```
outputSchema
```
  中声明。如果需要这些字段，请跳过输出验证重新运行。
- ```
{ skipped: true }
```
  —— 已绕过验证；
```
data
```
  是原始的、未检查的脚本输出。

读取被丢弃的字段 /
skipOutputDataValidation
。要接收原始的未验证结果，请选择退出输出验证（确切语法因环境而异——请查看你加载的参考文档）。输入验证永远不会被跳过。

修剪结果 /
filterOutputData
。要将大型结果缩小到你需要的字段，请传递一个jq表达式对

data

进行后处理（同样，确切语法因环境而异）。jq仅针对

data

运行，而非

{ data, meta }

结果包，因此请以

data

为根编写表达式（运行脚本的

--help

命令——或你的环境中的等效命令——查看其输出模式）。转换后的值会替换

data

，

meta

会被保留，且结果不会再次根据输出模式进行验证。

References

参考文档

Load the matching reference file before working in that area:

Reference	Covers	Load it when
`references/dropbox-api-gotchas.md`	Stone `.tag` union shape, `error_summary` error model, read-vs-write not-found asymmetry, path rules (root is `""` not `"/"` ), cursor pagination via sibling `/continue` endpoints, rate limits + namespace write-locking, upload-session flow, shared-link recovery, team-space targeting via `namespace_id`	Before making any direct Dropbox API calls or debugging unexpected API errors

在对应场景下工作前，请加载匹配的参考文档：

参考文档	涵盖内容	加载时机
`references/dropbox-api-gotchas.md`	`.tag` 联合结构、 `error_summary` 错误模型、读写操作中“未找到”的不对称性、路径规则（根路径为 `""` 而非 `"/"` ）、通过同级 `/continue` 端点实现游标分页、速率限制 + 命名空间写入锁定、上传会话流程、共享链接恢复、通过 `namespace_id` 定位团队空间	在直接调用Dropbox API或调试意外API错误前