dropbox-mcp

LLM エージェントに Dropbox アカウント（個人用、または Business/Team）への読み書きアクセスを Dropbox API v2 経由で提供する Model Context Protocol サーバーです。

問題

Dropbox 純正のデスクトップクライアントは、ファイルの同期を解決します。しかし、AI エージェントに、ローカルコピーを持たないアカウントへの制御されたアクセスを提供するものではありません。同期済みフォルダしか見えないエージェントは、2 TB のチームアーカイブを検索できず、共有リンクを作成できず、渡されていないファイルを読むこともできません。

このサーバーはそのギャップを埋めます。Dropbox HTTP API に直接通信するため、1 バイトもディスクに同期せずにアカウント全体を扱えます。さらに、そのアクセスは生の HTTP クライアントではなく、固定の MCP ツール群として公開されます。エージェントが取得するのは fetch ではなく dropbox_search です。

Related MCP server: Dropbox MCP Server

アーキテクチャ

files、search、sharing、account の 4 つのツールモジュールが、stdio 上で MCP を話す単一の McpServer に自身を登録します。すべてのモジュールは、Dropbox API が面倒にしている 2 つの要素、つまり OAuth トークンのライフサイクルと team-space 名前空間を管理する 1 つの HTTP クライアントを経由します。モジュールは起動時に 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

エンドポイントは 2 つのグループに分け、意図的に別々の関数として維持しています。RPC エンドポイントは JSON 入力/JSON 出力である一方、Content エンドポイントは引数を HTTP ヘッダに入れ、ボディをファイルのバイト列に使います。これらを 1 つの汎用 request() にまとめると、引数の格納先が暗黙に変わるパラメータになってしまうため、分離したままにしています。

実際に難しい部分

Dropbox Business/Team では、API はデフォルトでメンバーのホーム名前空間を参照します。実際の共有作業が置かれているチームフォルダはすべて、チームのルート名前空間側にあり、単に見えません。"" に対して list_folder を呼ぶと、メンバーのプライベートファイルだけが返り、エラーも、アカウントの大半が欠けているという手がかりもありません。権限の問題に見えますが、実際には権限の問題ではありません。

対策は、チームのルート名前空間を指す Dropbox-API-Path-Root ヘッダーを送ることです。そのルート名前空間の ID は users/get_current_account から取得できます。ここに再帰の罠があります。汎用 RPC ヘルパーはすべての呼び出しに path-root ヘッダーを付けるため、そのヘルパー自身が get_current_account を経由して名前空間を解決しようとすると、ヘッダー解決が自分自身を永遠に呼び続けることになります。そこで resolveRootNamespaceId() は、ヘルパーを迂回した意図的に素の fetch を発行し、結果をメモ化することで、余計な往復がプロセスごとに 1 回で済むようにしています（src/client.ts）。

同じ類のバグの小さな版もあります。Content エンドポイントは引数を Dropbox-API-Arg に渡しますが、HTTP ヘッダーは ASCII です。ファイル名にアクセント記号や絵文字が含まれると、API エラーを返すのではなく、fetch 内部で例外を投げます。apiArg() はヘッダーを構築する前に、非 ASCII のコードポイントをすべて \uXXXX へエスケープします。

やり直すなら変えたい点

1. テストなし。 実際のアカウントを相手に手作業で構築・検証しました。トークンリフレッシュの経路、401 リトライ、チャンク分割アップロードの境界条件こそ、モックしたトランスポートを使うテストで駆動すべきコードです。これらはまれにしか失敗せず、失敗すると講償コストが高いからです。

2. path-root キャッシュはプロセスローカルで、無効化されない。 ホストが自由に再起動してくれる stdio サーバーでは十分ですが、ユーザーがチーム間を移動し得る長期間動くプロセスには適していません。

3. dropbox_delete が確認の仕組みなしで公開されている。 Dropbox 自身の保持機能によって復旧できますが、破壊的なツールはホストに確認してもらうのに頼るどではなく、その旨をスキーマで示すべきです。

4. エラーが文字列に整形されている。 メッセージとあわせて構造化されたエラーコードを返せば、エージェントは文面を解析しなくても "rate limited" と "not found" を分岐できます。

セットアップ

Node.js 20+（開発時は 24）と Dropbox アカウントが必要です。

1. Dropbox アプリを作成する

1. Create app を選択 https://www.dropbox.com/developers/apps から。

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. ビルドして認証する

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 は認証 URL を表示し、貼り付けられたコードを受け取って、それをリフレッシュトークンと交換します。その後はサーバー自身がそのリフレッシュトークンを短命のアクセストークンと交換するようになります。

3. MCP ホストに登録する

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

ホストを再起動して、「私の Dropbox の使用量は？」のように質問してみてください。

ホストなしでサーバーを試す場合は次のとおりです:

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（アップロードセッションで大きなファイルを自動的にチャンク分割）。

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 の代理ヘッダーを含む注釈付きの完全な一覧については .env.example を参照してください。

ライセンス

MIT — LICENSE を参照してください。