dropbox-mcp

一个 Model Context Protocol 服务器，让 LLM 智能体能够通过 Dropbox API v2 对 Dropbox 账户（个人或 Business/Team）进行读写访问。

问题

Dropbox 自己的桌面客户端解决的是文件 同步。它没有解决的是：让 AI 智能体对本地没有副本的账户进行受控访问。一个只能看到同步文件夹的智能体，搜索不了 2 TB 的团队归档，生成不了共享链接，也读不了从未交付过它的文件。

而这个服务器正是来弥合这个缺口的。它直接面向 Dropbox HTTP API 通信，所以不用把单个字节落到磁盘就能覆盖整个账户；并且这种访问以一套固定的 MCP 工具暴露出来，而不是一个裸的 HTTP 客户端——智能体拿到的是 dropbox_search，而不是 fetch。

Related MCP server: Dropbox MCP Server

架构

四个工具模块（files、search、sharing、account）都注册在同一个 McpServer 下，通过 stdio 承载 MCP 通信。每个模组最后都会走同一个 HTTP 客户端，而这个客户端一手揽下了 Dropbox API 最挠头的两件事：OAuth 令牌的生命周期和 team-space 的命名空间。每个工具模块都支持在启动时用单项 DROPBOX_DISABLED_MODULES 独立禁用；因此，一个绝不能建公开分享链接的部署就直接不注册那个模块——这种能力是缺失，而不是规定产品。

  MCP host (Claude, etc.)
          | stdio (JSON-RPC)
  +-------v--------------------------------------+
  |  index.ts   module registry / stdio transport|
  +-------+--------------------------------------+
          |
  +-------v-------+ +--------+ +---------+ +---------+
  |  tools/files  | | search | | sharing | | account |
  +-------+-------+ +---+----+ +----+----+ +----+----+
          |             |           |           |
          +------+------+-----------+-----------+
                 |
        +--------v-----------------------------------+
        |  client.ts                                 |
        |   - refresh-token -> access-token cache     |
        |   - 401 retry with a forced refresh         |
        |   - Dropbox-API-Path-Root resolution        |
        |   - ASCII-safe Dropbox-API-Arg encoding     |
        +--------+-----------------------------------+
                 |
      RPC api.dropboxapi.com   Content content.dropboxapi.com

两类端点刻意被分成不同函数：RPC 端点是 JSON 进/JSON 出，而 Content CU 端呢，其参数放在 HTTP header 里，文件字节体放在 body 里。要是把二者塞进一个通用的 request() 里，就必须用一个参数来"默认地"决定参数去什么位置，因此两者保持分离。

真正难的部分

在 Dropbox 的 Business 团队里，API 默认使用成员的 home 命名空间。真正承载协作内容的团队文件夹却住在团队的 root 命名空间里，对 API 不可见。对空串 "" 调 list_folder，只会返回各成员仅个人的私有文件，别的都没有；无报错，也没有一丝提示「账户大部分内容其实没被覆盖」。看着像 permission 问题，其实不是。

修复方法是发 Dropbox-API-Path-Root 头指向团队根的命名空间，而那个命名空间的 identifier 要从 users/get_current_account 里拿。这引入了一个递归陷阱：通用 RPC 辅助函数会给每个请求都套上 path-root 头，所以如果“用它自己区调 get_current_account 来解析命名空间”，那么 header 的解析就会反复再触发 header 解析，没完没了。resolveRootNamespaceId() 因此，故意用一个不发辅助函数的裸 fetch 来做解析，并把结果 memoized 住，所以它在每个进程内只多绕一次网络往返（见 src/client.ts）。

同一类 bug 还有一个更小的版本：Content 端点的参数是要放 Dropbox-API-Arg 里的，row时 HTTP header 必须是 ASCII。文件名只要带一个符号，带带 emoji，fetch 就会直接挂掉，而不是返回一个 API 错误。而 apiArg() 是在构建该头前先把每个非 ASCII 码点转义 \uXXXX。

如果重写，我会改成

1. 补写 Tests。 现在这台伺服是海外手工对着一个真实账户 build 并手工。token-refresh 的路径、401 之后的 retry，以及分块上传的边界条件，正是应当用 mock transport 的测试来稳稳驱动的代码——也正因为它们“平时不宕，一宕就很贵”。

2. path-root 的缓存是 per-process 的，永不 invalid 化。 它适合 stdio 一个 host 能随便重启的 stateless 服务；但任何长生命周期、用户又可能真的被移其 team 就不是这种情况了。

3. dropbox_delete 裸暴露出来，没有任何确认述出的 UI能力。 Boxx 自带的 retention 保存了可恢复的 phav，则可坏副本工具自己要在 schema 里把“可恢复/有破坏性”明白标出，而不是只依赖 host 那边去问。

4. 错误全被 flatten 成一串 string。如果除了 message 之外还配一个结构化的错误 code，agent 就只需要靠核对读 reason “被限流”还是“没有一个样 not found-……” 而不是去 parse 一句懂。

准备

第四章 要求：Node 20+（Node 24 已开发）和 Dropbox 账户。

1. 新建一个 Dropbox 应用

1. 打开 https://www.dropbox.com/developers/apps，再点"Create app"（创建应用）。

2. 选 Scoped access 和 Full Dropbox。

3. 在 Permissions里开启 account_info.read、files.metadata.read、files.metadata.write、files.content.read、files.content.write、sharing.read、sharing.write之后点 Submit 。

4. 在 Settings 上复制 App key 和 App secret 。

2. 构建并授权

研究所 (需要上面复制的 appKey / AppSecret)

再回到文档——后面的是 "npm run"。重写成了：

2. 构建并授权

（下面环境变量列表会包含在 环境设置后在 config 前）

git clone <this-repo>
cd dropbox-mcp
npm install
npm run build

cp .env.example .env      # fill in DROPBOX_APP_KEY and DROPBOX_APP_SECRET
npm run auth              # prints DROPBOX_REFRESH_TOKEN — paste it into .env

运行 npm run auth 会打印一个授权（consent）URL；粘贴回来 code 之后，自动会指令之间换个 refresh token。之后那个服务器再自行把 refresh token 换成短时的 access token。

3. 在 MCP host 里注册

{
  "mcpServers": {
    "dropbox": {
      "command": "node",
      "args": ["/absolute/path/to/dropbox-mcp/dist/index.js"],
      "env": {
        "DROPBOX_APP_KEY": "your-app-key",
        "DROPBOX_APP_SECRET": "your-app-secret",
        "DROPBOX_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

然后重启 host 并问它像 「我的 Dropbox 用掉多少空间？」 这样的问题。

要想不经过 host 直接试这个服务器：

npm run inspect           # @modelcontextprotocol/inspector

工具

files — dropbox_list_folder dropbox_get_metadata dropbox_create_folder dropbox_move dropbox_copy dropbox_delete dropbox_get_temporary_link dropbox_read_file dropbox_upload（针对大文件通过 upload sessions 自动分块）。

search — dropbox_search 跨越文件与内容，可全账户范围，或只限定到某一个文件夹。

sharing — dropbox_create_shared_link dropbox_list_shared_links dropbox_get_shared_link_metadata dropbox_revoke_shared_link。

account — dropbox_get_current_account dropbox_get_space_usage。

配置

所有配置都走环境变量；完整的全注释列表见 .环境示例，包括命名空间控制（DROPBOX_PATH_ROOT）、读取上限（DROPBOX_MAX_READ_BYTES）、上传块大小，以及 team-app 模拟用的请求头。

许可证

MIT —— 见 LICENSE。