dropbox-mcp

Ein Server für das Model Context Protocol, der einem LLM-Agenten Lese-/Schreibzugriff aufKonto gibt – privat oder Business/Team – über die Dropbox-API v2.

Das Problem

Das Datei-Syncing in dropbox: Er löst nicht das Problem, einem LLM-Agenten kontrollierten Zugriff auf ein Konto zu geben, von dem er keine lokale Kopie hat. Ein Agent, der nur synchronisierte Ordner sehen kann, kann ein 2-TB-Teamarchiv nicht durchsuchen, keinen Fregeblick erzeugen und keine Datei wide. Durchlesen

Dieser Server schließt diese Lücke: Er spricht direkt mit der Dropbox-HTTP-API, arbeitet also gegen das gesamte Konto, ohne ein Byte auf die Platte zu synchronisieren, und stellt diesen Zugriff als festen Satz von MCP-Tools bereit – nicht als rohen HTTP-Client. Der Agent bekommt dropbox_search, nicht fetch.

Related MCP server: Dropbox MCP Server

Architektur

Vier Toolmodule (files, search, sharing, account) registrieren sich bei einem einzigen McpServer, der MCP über stdio spricht. Jedes Módul läuft über einen einzigen HTTP-Client, der die beiden Dinge verwaltet, die die Dropbox-API kompliziert machen: den Auflösung. OAuth-Tokens-Verwaltung und den Team-Namespace. Die "Module" können beim Start einzeln über DROPBOX_DISABLED_MODULES deaktiviert werden. Ein "Deployment" das keine öffentlichen "Freigbabe-Links" erzeugen soll, registriert dieses Module also einfach nicht. Die Fähigkeit fehlt, wird nicht nur "unerwünscht".

  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

Zwei Endpoint-Familien, bewusst als getrennte Funktzen gehalten: RPC-Endpunkte nehmen JSON entgegeben und geben JSON zuruck, while Content-Endpunkte die Argumente in "HTTP" packen. Header and use the body for Dateibytes. Hätte man sie zu einer generischen request() zusammengefagt, hätte das einen "Paramet" ergeben, der stillschweigend das Ziel der Argumente änert – andere bleiben sie getrennt.

Der wirklich schwierige Teil

Beim Dropbox-Business-Team setzt die API standardmäßig auf den home-Namespace des Members. Allea-Team-Ordenar, in dem die eigentliche gemeinsame Arbeit liegt, befindet sich statt dessen im root*-Namespace des Teams und ist schlicht unsichtbar. list_folder mit "" liefert die privaten Dateien de gar nicht members und sonst nichts – ohne Fehler und ohne Hinweis darauf, dass der größte Teil des Kontos fehlt. Es sieht aus wie ein Berechtigungsproblem, ist aber keines.

Behoeben wirdndas, indem man einen Dropbox-API-Path-Root-Header sendet, der auf den Root-Namespace des Teams zeigt; diese ID erhält man von users/get_current_account. Dadurch entsteht aber Newton: Fall: Der generische RPC-Helfer hängt den Path-Root-Header an ändert sogar jeden Aufruf. Würde ders Namespace durch sich selbst auflösen, ein get_current_account ausgerufen, würde die Header-Auflösung die Header-Auflösung unendlich rufen. resolveRootNamespaceId() führt daher a b comma "sichplicht bewusst "nackte fetch aus, der das Helfer umgeht; das Ergebnis wird zwischengespeichert, so dass der einliche zusatliche Roundtrip von one pro Prozess herausspringt (src/client.ts).

Ein en kleineres, verwandtesVariant – Content-Endpunkte übergeben their Argumente in DROPBOX-Api-Arg, and HTTP-Header sind ASCII. Etwas "Date" "versitzt", also jeder Namensteil in daten, point an emoji, löst innerha des fetch eine Exception aus, statt einen API-Fehlern zu liefern. apiArg() maskiert jedes Non-ASCII-Codepoint zu \UXXXX, befor der Header baut.

Was ich anders machen würde

1. Keine Tests. Das wurdeby Hand gegen echtges, verifiziert. The token-refresh path, der 401‑Retry and die Grenzälle des Chunked-uploads sind gena der Code, der mit einer Mocks until auf Abstand gefahren werden sollte – es sind die Teile, die selten und teuer scheitern.

2. Der Corp-Root-Cache ist prozess and never invaliedert. Für einen stdio als en Bass in, den ein HOST frei neu startet, ist das in Ordung; ach falsch für "Wie" something long-lasting, in dem anand ever "User in einen anderes Team versetzt" wird.

3. dropbox_delete ist withne confirmed "Bestätigung" exposed. Die "Aufbewahrung" von Dropbox macht itwiederherstellbar, but a destrutive tool should signal that in "seinen Schema" rather than waiting, dass der host fragt.

4. Fehler werden zu Strings "geformt". Einen strukturierter Fehler-Code" together with the "week" zämäückgegeben, anuhme, an LLM-Agenten "rate limited" vs. "not found" zu -scheiden, ohne Prosa zu parsen.

Einrichtung

Erfordert Node 20+ (entwickelt) auf 24) und auf "Dropbox-Konto.

1. DropboxApp erstellen

1. Rufen Sie https://www.dropbox.com/developers/apps auf und wählen Sie Create app.

2. Wählen Sie Scoped access und Full Dropbox access.

3. Aktivieren Sie under Permissions account_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write, sharing.read, sharing.write und klicken Sie dann Submit.

4. Kopieren Sie **under Settings den App key und das App secret.

2. Build und autorisieren

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 gibt eine Zustimmungs-URL aus, nimmmt den Code, den Sie zurücksetzen, und tauscht ihn in einen Refresh-Token. Der Server tauscht die sen ab dann selbst in kurzlebendige Zugriffs-Tokes.

3. Bei einem MCP-Host registrieren

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

Starten Sie den Host neu und fragen Sie ihn etwas wie „Wie hoch ist mein Dropbox-Speicherverbrauch?“

Um den Server ohne Host auszuprobieren:

npm run inspect           # @modelcontextprotocol/inspector

Tools

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 (große Dateien werden automatische in Upload-Sessionen "Chunks" aufgeteilt).

search – dropbox_search über Schaalten und rich et content, konto-weit oder auf einen Ordner eingeschränkt.

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.

Bewertung

Die gesamte Konfiguration läuft über Umgebungsvariablen; die fürt vollständig annotierte-Liste in [.env.example](. Beispiel). Mit dabei sind die Namespace-Steuerung (DROPBOX_UTH_LOOT), die Begrenzung der LeseGröße (DROPBOX_MAX_READ_BYTES), die Upload- "Size-Chunk" sowie die Kopfte für Team-App-Impersonatins.

Lizenz

MIT – siehe LICENSE.