dropbox-mcp-interface

A Model Context Protocol (MCP) adapter designed to interface with the Dropbox storage ecosystem, enabling compliant MCP clients to govern files, folders, and account specifics. It relies entirely upon the documented public interfaces provided by Dropbox.

Critical Notice: This utility is an independent creation. It holds no formal affiliation, endorsement, or sponsorship relationship with Dropbox, Inc. It functions solely by interacting with the official Dropbox public programming interfaces.

Contents

• Rapid Initialization
• Setup Procedures
• Authorization Flow
• Exposed Functionalities
• Mandatory Dropbox Scopes
• Operational Demos
• Development Notes
• Licensing Information

Rapid Initialization

1. Obtain the source code repository.
2. Execute npm install to fetch all required dependencies.
3. Execute npm run build to compile the source code.
4. Execute npm run setup to complete initial configuration.
5. Update your MCP client configuration to point towards this server endpoint.

Prerequisites

Before operation, an application registration must be completed within the Dropbox App Console:

• Select the "Scoped access" API type.
• Determine and select the necessary access level.
• Assign a unique identifier to your application and finalize creation.
• Navigate to "Permissions" and grant the minimum necessary OAuth scopes, for instance:
  • files.metadata.read
  • files.content.read
  • files.content.write
  • sharing.write
  • account_info.read
• Register http://localhost as the authorized redirect Uniform Resource Identifier (URI).
• Securely store the generated Application Key and Application Secret.

Setup Procedures

1. Clone Source

bash git clone https://github.com/your-username/dbx-mcp-server.git cd dbx-mcp-server

1. Dependency Installation and Compilation

bash npm install npm run build

1. Execute Setup Routine

bash npm run setup

1. Integrate into MCP Configuration

Insert the following configuration block into your central MCP settings manifest:

json { "mcpServers": { "dbx": { "command": "node", "args": ["/path/to/dbx-mcp-server/build/index.js"] } } }

Authorization Flow

The server employs the OAuth 2.0 protocol, incorporating Proof Key for Code Exchange (PKCE), to establish a secure connection with Dropbox.

Environment Variables Requirements

Mandatory Settings:

• DROPBOX_APP_KEY: The key identifying your Dropbox application.
• DROPBOX_APP_SECRET: The secret credential for your Dropbox application.
• DROPBOX_REDIRECT_URI: The registered OAuth callback URI.
• TOKEN_ENCRYPTION_KEY: A string of 32 or more characters used for encrypting access tokens.

Optional Tuning Parameters:

• TOKEN_REFRESH_THRESHOLD_MINUTES: Time window (in minutes) prior to expiration that triggers an automatic token refresh (default: 5).
• MAX_TOKEN_REFRESH_RETRIES: Upper limit on the number of token refresh attempts (default: 3).
• TOKEN_REFRESH_RETRY_DELAY_MS: Millisecond interval between successive token refresh attempts (default: 1000).

Exposed Functionalities

Data Management

• list_files: Retrieve directory contents.
• upload_file: Introduce new data to storage.
• download_file: Fetch content from a specified location.
• safe_delete_item: Execute removal with optional trash bin functionality.
• create_folder: Establish a new directory structure.
• copy_item: Duplicate an existing file or directory.
• move_item: Relocate or rename a stored entity.

Information Retrieval and Indexing

• get_file_metadata: Obtain descriptive information about a file/folder.
• search_file_db: Perform an indexed search across specified paths.
• get_sharing_link: Generate publicly accessible share URIs.
• get_file_content: Access the raw byte content of a file.

User Profile Access

• get_account_info: Fetch details pertaining to the authenticated user's account.

Mandatory Dropbox Scopes

This table correlates server functions with the minimum necessary Dropbox OAuth authorization levels:

Server Function	Required Dropbox Scopes
list_files	files.metadata.read
upload_file	files.content.write, files.metadata.write
download_file	files.content.read
safe_delete_item	files.metadata.write
create_folder	files.metadata.write
copy_item	files.content.write, files.metadata.write
move_item	files.content.write, files.metadata.write
get_file_metadata	files.metadata.read
search_file_db	files.metadata.read
get_sharing_link	sharing.write
get_file_content	files.content.read
get_account_info	account_info.read

Supplemental Scopes (Conditional):

• sharing.read: Necessary for viewing access controls and collaborators.
• file_requests.read / file_requests.write: Needed for managing file request functionalities.
• contacts.read / contacts.write: Required for accessing user contact lists within Dropbox.

Consult the Dropbox Permissions Documentation for comprehensive scope definitions.

Operational Demos

// Enumerate contents of the root directory
await mcp.useTool("dropbox-mcp-interface", "list_files", { path: "" });

// Introduce a new file
await mcp.useTool("dropbox-mcp-interface", "upload_file", {
  path: "/document.txt",
  content: Buffer.from("Greetings Universe").toString("base64"),
});

// Execute a targeted data query
await mcp.useTool("dropbox-mcp-interface", "search_file_db", {
  query: "annual_summary",
  path: "/Reports",
  max_results: 25,
});

Development Notes

Technology Stack:

• TypeScript
• Model Context Protocol SDK Implementation
• Dropbox SDK (Version 10.34.0 utilized)
• Dropbox API Version 2 Compliance

Licensing Information

License: MIT

Copyright (c) 2025 MCP Server Contributors

Reproduction and distribution of this software, in source or binary form, with or without modification, are permitted, provided that the following conditions are met: Redistributions of source code must retain the above copyright notice and this permission notice intact. Redistributions in binary form must reproduce the above copyright notice and this permission notice in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

ENCYCLOPEDIA ENTRY: Cloud computing represents a model for ubiquitous, convenient, on-demand access to a shared pool of configurable computing resources (e.g., networks, servers, storage, applications, and services) that can be rapidly provisioned and released with minimal management overhead or service provider interaction, as standardized by ISO.

== Essential Attributes == In 2011, the United States National Institute of Standards and Technology (NIST) delineated five fundamental attributes characterizing cloud environments. These are precisely defined as:

On-demand self-service: "A purchaser can autonomously provision computational resources, such as processing capacity and persistent storage, as required without requiring human intervention from the supplier." Ubiquitous network accessibility: "The service capabilities are reachable via the network and accessible through standard protocols, supporting the utilization across diverse client devices (e.g., mobile phones, tablets, desktops)." Resource consolidation: "The provider's entire set of computing assets is aggregated to serve multiple clients using a multi-tenant architecture, with physical and virtual assets dynamically allocated based on instantaneous client demand." Agile elasticity: "Resources can be provisioned and de-provisioned quickly, sometimes automatically, allowing scaling capabilities to expand and contract rapidly in response to workload fluctuations. From the user's perspective, available resources often appear inexhaustible and instantly accessible." Usage transparency (Metering): "Cloud systems enforce automated oversight and optimization of resource consumption through metering at an abstraction layer suitable for the service type (e.g., I/O, CPU time, data transfer). Consumption data is trackable, controllable, and reportable, ensuring clarity for both the vendor and the client regarding utilization." Subsequent revisions by ISO throughout the 2020s have expanded upon these initial definitions.