dropbox-mcp
This server exposes Dropbox APIs to LLM agents as MCP tools, focused on file recovery, discovery, and single-file operations.
Restore deleted files:
dropbox_restore(latest revision),dropbox_restore_batch(multiple files), anddropbox_restore_revision(specific revision ID).Download cloud-only files:
dropbox_downloadforces a file from Dropbox servers into the local Dropbox folder, bypassing Smart Sync.Upload, move, and delete files:
dropbox_upload(single file, add/overwrite, ≤150 MB),dropbox_move(server-side move/rename with optional autorename), anddropbox_delete(to trash, recoverable ~30 days).Search and discover content:
dropbox_searchfinds files by name or content;dropbox_list_deletedlists recoverable deleted files in a folder.Inspect file metadata and history:
dropbox_file_inforeturns size, modified time, revision, and content hash;dropbox_list_revisionslists up to 100 past revisions with rev IDs and sizes.
Provides tools for interacting with Dropbox API, enabling file recovery, revision management, search, download, and metadata retrieval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dropbox-mcp restore the file /Projects/report-final.docx I accidentally deleted"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
dropbox-mcp
An MCP (Model Context Protocol) server that exposes the Dropbox API as tools for
LLM agents. Built on the TypeScript MCP SDK v2
(@modelcontextprotocol/server) and the official dropbox npm SDK.
Built on @modelcontextprotocol/server v2. The negotiated protocol version is
2025-11-25 (the SDK's LATEST_PROTOCOL_VERSION): stateless
per-request metadata, server/discover capability negotiation, and no session-scoped
initialize handshake. Legacy 2025-era MCP clients continue to work on the same stdio
transport.
Focus: recovery and discovery on an existing Dropbox account — restoring deleted files, listing revisions, searching content, and force-downloading cloud-only files. The server talks to the Dropbox server-side API, not the local sync folder, so it can see and restore files that local sync has already deleted.
Tools
All tool names are prefixed dropbox_ to avoid collisions with other MCP servers.
Tool | Behavior | Read-only |
| Restore the most recent server-side revision of a deleted file. | No |
| Restore multiple files in one call; reports per-path result. | No |
| Restore a specific revision ID (e.g., a known-good earlier version). | No |
| Force-download a file from Dropbox to the local sync folder, bypassing Smart Sync cloud-only state. | No |
| Upload a single local file to Dropbox. Source defaults to the local-folder mirror of the destination path; | No |
| Move or rename a file/folder server-side (no download). | No |
| Delete a file or folder (goes to trash; recoverable via | No |
| Search by filename or content across the account. Returns path, size, modified date. | Yes |
| List deleted entries in a folder (optionally recursive). Input for restore workflows. | Yes |
| Return size, modified time, revision ID, and content hash for a path. | Yes |
| List up to 100 revisions of a file with rev ID, size, and modified time. | Yes |
Atomic single-file ops vs. bulk sync: these tools are for one-file or interactive operations. For syncing or sorting whole folders (10s–1000s of files), use the companion dropbox skill's dbx_sync.py (bulk, move-aware, plan→review→execute). The split: this server is the atomic + recovery layer; the skill is the orchestration layer.
Related MCP server: Dropbox MCP Server
Installation
Prerequisites
Bun 1.4 or newer (package manager and script runner)
Node.js 24 or newer (MCP server runtime — the shipped
bundle/index.mjsanddist/index.jsare launched withnode)A Dropbox account and a Dropbox app with
files.content.read,files.content.write, andfiles.metadata.readscopes
Install
git clone https://github.com/danielsimonjr/dropbox-mcp.git
cd dropbox-mcp
bun install
bun run buildThe build emits dist/index.js, which is the entry point used below.
Authentication
The server loads credentials from ~/.claude/channels/dropbox/.env on startup,
with process.env taking precedence over the file (so the MCP host can override
via .mcp.json env). Create the file and paste in the template below, then
fill in your values:
mkdir -p ~/.claude/channels/dropbox
touch ~/.claude/channels/dropbox/.envTemplate:
# --- Option A: OAuth 2 refresh token (recommended) ---
# Create an app at https://www.dropbox.com/developers/apps, enable the scopes
# files.content.read, files.content.write, files.metadata.read, then run the
# OAuth flow once to obtain a refresh token.
DROPBOX_REFRESH_TOKEN=
DROPBOX_APP_KEY=
DROPBOX_APP_SECRET=
# --- Option B: Long-lived access token (fallback) ---
# Leave blank if you are using Option A above.
DROPBOX_ACCESS_TOKEN=
# --- Optional ---
# Local Dropbox sync folder. Used by dropbox_download to write files.
# Defaults to ~/Dropbox if unset.
# DROPBOX_LOCAL_PATH=C:\Users\you\DropboxTwo auth modes are supported, tried in order:
OAuth 2 refresh token (recommended): set
DROPBOX_REFRESH_TOKEN,DROPBOX_APP_KEY, andDROPBOX_APP_SECRET. Access tokens are refreshed automatically, so credentials do not expire.Legacy long-lived access token (fallback): set
DROPBOX_ACCESS_TOKENonly. Simpler to obtain, but tokens expire after a few hours for newer apps.
Running the server
Directly (for testing)
node dist/index.jsThe server communicates over stdio, so there is no interactive output — it waits
for MCP protocol messages on stdin. On connect it logs "dropbox-mcp: connected on stdio" to stderr.
With the MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.jsRegistering with Claude Code
Add an entry to your .mcp.json:
{
"mcpServers": {
"dropbox-mcp": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/dropbox-mcp/dist/index.js"]
}
}
}Restart Claude Code (or run /reload-plugins) for the registration to take effect.
Examples
Restore a file deleted by accident:
Agent: dropbox_restore(path="/Projects/report-final.docx")
Result: Restored: /Projects/report-final.docx (rev: abc123, size: 45678 bytes)Find a file without knowing its exact location:
Agent: dropbox_search(query="RSP consciousness paper", max_results=5)
Result: Found 3 results for 'RSP consciousness paper':
1.25 MB 2026-02-18 /Misc/Philosophy/Beyond the Bat/paper.pdf
0.31 MB 2026-02-10 /Misc/Philosophy/Beyond the Bat/drafts/outline.md
...Roll back to a specific earlier revision:
Agent: dropbox_list_revisions(path="/report.docx", limit=5)
Agent: dropbox_restore_revision(path="/report.docx", rev="0123abc")Upload, move, and delete a single file:
Agent: dropbox_upload(path="/Misc/notes.md", mode="overwrite")
Result: Uploaded: /Misc/notes.md (2048 bytes, mode: overwrite)
Agent: dropbox_move(from_path="/Misc/notes.md", to_path="/Misc/Archive/notes.md")
Result: Moved: /Misc/notes.md -> /Misc/Archive/notes.md
Agent: dropbox_delete(path="/Misc/Archive/old-draft.md")
Result: Deleted: /Misc/Archive/old-draft.md (recoverable via dropbox_restore for ~30 days)Security notes
The
.envfile holds long-lived credentials — keep it out of version control (the default.gitignorealready excludes.envfiles).Mutating tools (restore, download, upload, move, delete) change Dropbox or local state. Agents should confirm intent before invoking them — especially
dropbox_deleteon a folder (removes all contents) anddropbox_restore_batch. Deletes go to Dropbox trash and are recoverable viadropbox_restorefor ~30 days.The server binds to no network ports — communication is stdio only. The only outbound connection is to
api.dropbox.comover HTTPS.Logs go to stderr, never stdout (stdout is reserved for MCP protocol frames).
Development
Bun is the package manager and script driver; Node remains the long-lived MCP
runtime (the Claude Code plugin entry still uses node …/bundle/index.mjs).
bun run typecheck # tsc --noEmit
bun run test # vitest run (full suite)
bun run build # emit dist/
bun run bundle # rebuild bundle/index.mjs (plugin artifact)The test suite covers config loading, every output formatter, the tool handlers
(both read-only and mutating), protocol negotiation, and a smoke test asserting
TOOLS↔HANDLERS symmetry.
For changes to the tool surface, update both this README and CHANGELOG.md in the
same commit.
License
MIT — see LICENSE.
Available Tools
11 toolsdropbox_deleteADestructive
Delete a file or folder on Dropbox. The item moves to Dropbox trash and is recoverable via dropbox_restore for ~30 days (longer on some plans). Deleting a folder removes all of its contents. Confirm intent before deleting folders.
Inputs: path (required).
dropbox_downloadADestructive
Force-download a file from Dropbox servers to the local Dropbox folder. Useful when Smart Sync keeps files cloud-only.
Inputs: path (required).
dropbox_file_infoBRead-only
Get metadata for a file on Dropbox servers: size, modified date, revision, content hash.
Inputs: path (required).
dropbox_list_deletedARead-only
List recently deleted files in a Dropbox folder. Shows files that can be restored.
Inputs: path (required), recursive.
dropbox_list_revisionsARead-only
List all available revisions of a file. Useful for finding older versions to restore.
Inputs: path (required), limit.
dropbox_moveADestructive
Move or rename a file or folder on Dropbox server-side (no download/re-upload). Use for cross-folder relocation or renaming. Set autorename=true to auto-rename instead of failing when the destination already exists.
Inputs: to_path (required), from_path (required), autorename.
dropbox_restoreADestructive
Restore a deleted file from Dropbox's server-side history. Finds the most recent revision and restores it.
Inputs: path (required).
dropbox_restore_batchADestructive
Restore multiple deleted files from Dropbox history.
Inputs: paths (required).
dropbox_restore_revisionBDestructive
Restore a specific revision of a file by revision ID.
Inputs: rev (required), path (required).
dropbox_searchARead-only
Search for files on Dropbox by name or content. Returns results with path, size, and modified date.
Inputs: query (required), path, max_results.
dropbox_uploadADestructive
Upload a local file to Dropbox (single file, atomic). Source defaults to the local Dropbox-folder mirror of path; pass local_path to upload an arbitrary local file. Mode 'add' (default) fails if the destination exists; 'overwrite' replaces it. Files larger than 150 MB are rejected (Dropbox requires a chunked upload session for those — use the desktop client). For bulk uploads of many files, use the dropbox skill's dbx_sync.py instead.
Inputs: path (required), mode, local_path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a clearly distinct purpose: delete, download, file info, listing deleted files/revisions, move, restore (deleted, batch, specific revision), search, and upload. No two tools overlap in functionality, and descriptions clarify any potential confusion between restore variants.
Most tools follow a consistent 'dropbox_verb_noun' pattern (e.g., dropbox_delete, dropbox_search). The minor exception is 'dropbox_file_info' which uses a noun-noun form instead of verb-noun, but overall the pattern is clear and predictable.
With 11 tools, the server is well-scoped for a file management service like Dropbox. It covers essential operations (CRUD, search, version history, restoration) without being bloated or insufficient.
The tool set covers core file operations: upload, download, delete, move, search, and version/restoration. Minor gaps exist, such as no explicit folder creation or sharing tools, but these are acceptable for a basic file management interface.
Maintenance
Related MCP Connectors
Unofficial Dropbox MCP Pack — wraps the Dropbox API v2
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Search, browse, and read your Dropbox files. Find documents by name or content, list folders, and…
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceThis read-only MCP Server allows you to connect to Dropbox data from Claude Desktop through CData JDBC Drivers. Free (beta) read/write servers available at https://www.cdata.com/solutions/mcp1MIT
- FlicenseAqualityNot gradedmaintenanceA local MCP server that enables Claude to manage Dropbox accounts through tools for file manipulation, searching, and sharing. It supports operations such as listing folders, moving files, creating shared links, and monitoring storage usage via natural language commands.10-
- AlicenseNot gradedqualityBmaintenanceEnables Dropbox file operations such as listing, searching, downloading, and creating folders via the Dropbox API v2 through MCP.285 npmMIT
- AlicenseAqualityCmaintenanceMCP server enabling file operations (list, search, read, rename, move) on Google Drive and OneDrive.21MIT