Dropbox Integration Gateway for MCP

This module acts as an intermediary server, adhering to the Model Context Protocol (MCP) specification, designed to abstract and expose Dropbox functionality to authorized MCP clients.

Crucial Notification: This utility is an independent development and holds no official affiliation, endorsement, or sponsorship from Dropbox, Inc. Its operation strictly relies upon leveraging Dropbox's publicly accessible APIs.

Primary Index

• Initial Setup
• Installation Procedure
• Access Granting
• Exposed Capabilities
• Parameterization
• Operational Illustrations
• Verification Protocols
• Contribution Guidelines
• Licensing Terms

Initial Setup

1. Obtain a local copy of the source repository.
2. Execute npm install to resolve all required package dependencies.
3. Run npm run build to compile the source code into executable assets.
4. Configure an application within the Dropbox Developer Portal:
5. Select the 'Scoped access' API variant.
6. Designate the required level of access granularity.
7. Name your creation and finalize application setup.
8. Within the 'Permissions' section, mandate the following scopes:
   • files.metadata.read
   • files.content.read
   • files.content.write
   • sharing.write
   • account_info.read
9. Set the callback endpoint to http://localhost:3000/callback.
10. Securely record the generated App Key and App Secret.

11. Initiate the prerequisite configuration script: bash npm run setup

12. Update your primary MCP configuration to reference this newly established server endpoint.

Installation Procedure

1. Repository Cloning

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

1. Dependency Resolution and Compilation

bash npm install npm run build

1. Bootstrap Configuration Execution

bash npm run setup

1. MCP Manifest Integration

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

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

Access Granting

The server implements secure authorization utilizing the OAuth 2.0 framework, specifically employing Proof Key for Code Exchange (PKCE) when communicating with Dropbox services.

Required Environment Variables

• DROPBOX_APP_KEY: The unique identifier for your registered Dropbox application.
• DROPBOX_APP_SECRET: The confidential secret associated with your application.
• DROPBOX_REDIRECT_URI: The mandated URI endpoint for OAuth redirection.
• TOKEN_ENCRYPTION_KEY: A cryptographic key (minimum 32 characters) utilized for securing stored access tokens.

Optional Parameters

• TOKEN_REFRESH_THRESHOLD_MINUTES: Time window (in minutes) prior to expiry that triggers an automatic token renewal cycle (Default: 5).
• MAX_TOKEN_REFRESH_RETRIES: Maximum allowed attempts for token renewal operations (Default: 3).
• TOKEN_REFRESH_RETRY_DELAY_MS: Millisecond pause enforced between successive token refresh attempts (Default: 1000).

Exposed Capabilities

Artifact Management

• list_files: Retrieve contents listing for a specified directory path.
• upload_file: Transfer data content to a designated path within Dropbox.
• download_file: Fetch content data from a specified Dropbox location.
• safe_delete_item: Execute deletion with reliance on the Dropbox recycle bin feature.
• create_folder: Provision a new directory structure.
• copy_item: Duplicate an existing file or directory entity.
• move_item: Relocate or rename a file/directory entity.

Data Inspection and Retrieval

• get_file_metadata: Query detailed informational attributes about an artifact.
• search_file_db: Perform pattern matching searches across the file system index.
• get_sharing_link: Generate publicly accessible or controlled sharing hyperlinks.
• get_file_content: Retrieve the raw binary or textual payload of a file.

User Profile Access

• get_account_info: Fetch current user account configuration details.

Operational Illustrations

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

// Ingest a file payload await mcp.useTool("dropbox-connector-mcp", "upload_file", { path: "/initial_doc.md", content: Buffer.from("System initialization complete").toString("base64"), });

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

Verification Protocols

Execute the integrated test harness to confirm system integrity:

bash npm test

Tests validate all implemented routines, encompassing authentication handshake, data manipulation utilities, and error containment measures.

Test Module Organization

The test suite is compartmentalized for systematic validation:

• Dropbox Service Tests: Focus on core object manipulation (e.g., upload, read, traverse, delete).
• User Context Tests: Verify functions accessing user-specific configuration data.
• Query and Recovery Tests: Validate search capabilities and recycle bin interaction.
• Protocol Resource Layer Tests: Confirm successful integration with the MCP resource framework.

Test Data Management

Tests utilize ephemeral, time-stamped identifiers for file/folder creation to prevent namespace collisions. All artifacts generated during testing are systematically purged upon test completion.

Targeted Test Execution

For focused testing:

bash npm test -- tests/service/artifact-operations.test.ts # Execute a single file npm test -- -t "should handle concurrent uploads" # Execute by description match

Diagnostic Assistance

If test execution falters due to timing or credential issues:

1. Verify that mock configurations within tests/setup.ts align with expected service behaviors.
2. Confirm initialization settings for ancillary test execution aids.
3. For issues related to Jest scoping, refrain from referencing imported variables within mock factory definitions.

Contribution Guidelines

Developed utilizing:

• TypeScript Language
• Model Context Protocol Software Development Kit
• Dropbox SDK (Version 10.34.0 or later)
• Dropbox API Version 2 Specification

Licensing Terms

This software is distributed under the MIT License.

Copyright (c) 2025 MCP Server Developers Collective

Permission is unconditionally granted to any individual obtaining a copy of this software and associated documentation to engage in all rights related to the Software without constraint, including but not limited to the rights to utilize, duplicate, revise, aggregate, disseminate, license, sell derivative works, and permit recipients to execute these actions, subject only to the following stipulation:

The preceding copyright declaration and this specific grant notice must be included in all duplications or substantial segments of the Software.

THE SOFTWARE IS SUPPLIED "AS IS," DEVOID OF ANY WARRANTY, EXPRESS OR IMPLIED, INCLUDING BUT NOT CONFINED TO WARRANTIES OF MARKETABILITY, SUITABILITY FOR A SPECIFIC OBJECTIVE, AND NON-INFRINGEMENT. THE AUTHORS OR COPYRIGHT OWNERS BEAR NO LIABILITY FOR ANY DEMAND, DAMAGE, OR OTHER RESPONSIBILITY, WHETHER IN LEGAL ACTION, CONTRACT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE UTILIZATION OF OTHER DEALINGS WITHIN THE SOFTWARE.