amgadabdelhafez/dbx-mcp-server

A Model Context Protocol (MCP) server that provides integration with Dropbox, allowing MCP-compatible clients to interact with Dropbox through a set of powerful tools.
Important Disclaimer: This project is not affiliated with, endorsed by, or sponsored by Dropbox. It is an independent integration that works with Dropbox's public API.
## Table of Contents
Quick Start
Installation
Authentication
Available Tools
Required Dropbox Permissions
Usage Examples
Development
License
## Quick Start
1. Clone the repository
2. Run npm install to install dependencies
3. Run npm run build to build the project
4. Run npm run setup
5. Configure your MCP client to use the server
## Prerequisites
Register a Dropbox app at Dropbox App Console:
Choose "Scoped access" API
Choose the access type your app needs
Name your app and click "Create app"
Under "Permissions", select the desired permissions for the actions you will be using, for example:
files.metadata.read
files.content.read
files.content.write
sharing.write
accountinfo.read
Add http://localhost as your redirect URI
Note your App key and App secret
## Installation
1. Clone the repository
bash
git clone https://github.com/your-username/dbx-mcp-server.git
cd dbx-mcp-server
2. Install dependencies and build
bash
npm install
npm run build
3. Run the setup script
bash
npm run setup
4. Add to MCP settings
Add the following to your MCP settings file:
json
"mcpServers": {
"dbx": {
"command": "node",
"args": ["/path/to/dbx-mcp-server/build/index.js"]
## Authentication
The server uses OAuth 2.0 with PKCE for secure authentication with Dropbox.
### Environment Variables
Required:
DROPBOXAPPKEY: Your Dropbox app's key
DROPBOXAPPSECRET: Your Dropbox app's secret
DROPBOXREDIRECTURI: OAuth redirect URI
TOKENENCRYPTIONKEY: 32+ character key for token encryption
Optional:
TOKENREFRESHTHRESHOLDMINUTES: Minutes before expiration to refresh token (default: 5)
MAXTOKENREFRESHRETRIES: Maximum number of refresh attempts (default: 3)
TOKENREFRESHRETRYDELAYMS: Delay between refresh attempts in ms (default: 1000)
## Available Tools
### File Operations
listfiles: List files in a directory
uploadfile: Upload a file
downloadfile: Download a file
safedeleteitem: Safely delete with recycle bin support
createfolder: Create a new folder
copyitem: Copy a file or folder
moveitem: Move or rename a file/folder
### Metadata and Search
getfilemetadata: Get file/folder metadata
searchfiledb: Search files and folders
getsharinglink: Create sharing links
getfilecontent: Get file contents
### Account Operations
getaccountinfo: Get account information
## Required Dropbox Permissions
Below is a mapping of server actions to the minimum Dropbox OAuth scopes (permissions) required:
| Server Action | Required Dropbox Scopes |
| listfiles | files.metadata.read |
| uploadfile | files.content.write, files.metadata.write |
| downloadfile | files.content.read |
| safedeleteitem | files.metadata.write |
| createfolder | files.metadata.write |
| copyitem | files.content.write, files.metadata.write |
| moveitem | files.content.write, files.metadata.write |