Dropbox MCP Server

🚀 dbx-mcp-server

A Model Context Protocol (MCP) server integrated with Dropbox, enabling interactions between MCP-compatible clients and Dropbox through a set of powerful tools.

⚠️ Important Note

This project is not affiliated with, endorsed by, or sponsored by Dropbox. It's an independent integration that works with Dropbox's public API.

📑 Table of Contents

• 🚀 Quick Start
• 📦 Installation
• 🔑 Authentication
• 🛠️ Available Tools
• ⚙️ Configuration
• 💻 Usage Examples
• 🧪 Testing
• 👨‍💻 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. Create a new app in the Dropbox App Console:
   • Generate an app key.
5. Configure the app key in environment variables:
   • DROPBOX_APP_KEY
   • DROPBOX_APP_SECRET
6. Run the project:

   npm run start
   

📦 Installation

To install the project and run the examples, follow these steps:

1. Clone the repository:

   git clone [repository URL]
   cd dbx-mcp-server
   

2. Install dependencies:

   npm install
   

3. Configure environment variables:
   • DROPBOX_APP_KEY: Your Dropbox app key.
   • DROPBOX_APP_SECRET: Your Dropbox app secret.
4. Run the project:

   npm run start
   

🔑 Authentication

This server uses PKCE (industry standard) based on OAuth 2.0 for authentication. Here are the main authentication steps:

1. The client requests an authorization URL:

   GET https://accounts.dropbox.com/oauth2/authorize?client_id=APP_KEY&response_type=code&redirect_uri=REDIRECT_URI
   

2. After the user authorizes the app, the server redirects to the specified callback URL with an authorization code.
3. The client requests an access token using the authorization code:

   POST https://api.dropbox.com/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
   

4. The server returns an access token and a refresh token:

   {
     "access_token": "ACCESS_TOKEN",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "REFRESH_TOKEN"
   }
   

🛠️ Available Tools

Here are the main features provided by this server:

File Operations

1. Upload a file:

   POST /files/upload
   Content-Type: multipart/form-data
   
   file=@/path/to/file
   

2. Download a file:

   GET /files/download?file_id=FILE_ID
   

3. List files:

   GET /files/list?directory=DIRECTORY_ID
   

Metadata Search

1. Search for files and directories:

   POST /metadata/search
   Content-Type: application/json
   
   {
     "query": "SEARCH_TERM"
   }
   

2. Get file metadata:

   GET /metadata/file?file_id=FILE_ID
   

Directory Management

1. Create a directory:

   POST /directories/create
   Content-Type: application/json
   
   {
     "name": "DIRECTORY_NAME",
     "parent_id": "PARENT_DIRECTORY_ID"
   }
   

2. Delete a directory:

   DELETE /directories/delete?directory_id=DIRECTORY_ID
   

⚙️ Configuration

To configure environment variables on the server, add the following variables:

• DROPBOX_APP_KEY: Your Dropbox app key.
• DROPBOX_APP_SECRET: Your Dropbox app secret.
• PORT: Optional, default is 3000. Specify the port on which the server runs.

💻 Usage Examples

Example 1: Uploading and Downloading Files

1. Upload a file:

   curl -X POST http://localhost:3000/files/upload \
    -F "file=@/path/to/file.txt"
   

2. Download a file:

   curl http://localhost:3000/files/download?file_id=FILE_ID
   

Example 2: Searching for Files

curl -X POST http://localhost:3000/metadata/search \
  -H "Content-Type: application/json" \
  -d '{"query": "search_term"}'

🧪 Testing

Overview

To test the server functionality, run the following command:

npm test

Detailed Steps

1. Clone the repository and install dependencies:

   git clone [repository URL]
   cd dbx-mcp-server
   npm install
   

2. Run the tests:

   npm test
   

Custom Testing

To run specific tests or test groups, use the following commands:

npm test -- tests/dropbox/search-delete.test.ts  # Run a specific test file
npm test -- -t "should search for files"        # Run tests matching the description

❌ Error Handling

The server returns the following error codes:

• 401 Unauthorized: Invalid or expired token.
• 403 Forbidden: Blocked operation.
• 404 Not Found: Resource not found.
• 500 Internal Server Error: Internal server error.

📚 Dependencies

The project depends on the following libraries:

• express: Web framework.
• multer: File upload handling.
• dotenv: Environment variable loading.

📄 License

This project is licensed under the MIT License.

👏 Contributors

Thank you to all contributors!

🐞 Issue Reporting

If you encounter any issues, please submit them on [GitHub Issues](https://github.com/[repository URL])/issues.

📚 References

• Dropbox API Documentation
• Express Official Documentation
• Multer Official Documentation

💡 Usage Tip

This example code is intended to provide a starting point. The specific implementation may need to be adjusted according to actual requirements.