dbx-mcp-server

一个提供与Dropbox集成的模型上下文协议（MCP）服务器，允许兼容MCP的客户端通过一组强大的工具与Dropbox进行交互。

重要声明： 本项目与Dropbox无关联，也未得到Dropbox的认可或赞助。这是一个独立的集成，使用Dropbox的公共API工作。

目录

• 快速开始
• 安装
• 认证
• 可用工具
• 配置
• 使用示例
• 测试
• 开发
• 许可证

快速开始

1. 克隆仓库

2. 运行 npm install 安装依赖项

3. 运行 npm run build 构建项目

4. 在Dropbox应用控制台注册一个Dropbox应用：

   • 选择"Scoped access" API
   • 选择您的应用需要的访问类型
   • 命名您的应用并点击"创建应用"
   • 在"权限"下，选择所需的权限：
     • files.metadata.read
     • files.content.read
     • files.content.write
     • sharing.write
     • account_info.read
   • 添加 http://localhost:3000/callback 作为您的重定向URI
   • 记住您的App key和App secret

5. 运行设置脚本： bash npm run setup

6. 配置您的MCP客户端以使用该服务器

安装

1. 克隆仓库

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

2. 安装依赖项并构建

   bash npm install npm run build

3. 运行设置脚本

   bash npm run setup

4. 添加到MCP设置

   将以下内容添加到您的MCP设置文件中：

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

认证

服务器使用带有PKCE的OAuth 2.0来安全地与Dropbox进行认证。

环境变量

必需：

• DROPBOX_APP_KEY: 您的Dropbox应用的key
• DROPBOX_APP_SECRET: 您的Dropbox应用的secret
• DROPBOX_REDIRECT_URI: OAuth重定向URI
• TOKEN_ENCRYPTION_KEY: 用于令牌加密的32个字符以上的密钥

可选：

• TOKEN_REFRESH_THRESHOLD_MINUTES: 在过期前刷新令牌的分钟数（默认值：5）
• MAX_TOKEN_REFRESH_RETRIES: 最大刷新尝试次数（默认值：3）
• TOKEN_REFRESH_RETRY_DELAY_MS: 刷新尝试之间的延迟（毫秒）（默认值：1000）

可用工具

文件操作

• list_files: 列出目录中的文件
• upload_file: 上传文件
• download_file: 下载文件
• safe_delete_item: 支持回收站的安全删除
• create_folder: 创建新文件夹
• copy_item: 复制文件或文件夹
• move_item: 移动或重命名文件/文件夹

元数据和搜索

• get_file_metadata: 获取文件/文件夹元数据
• search_file_db: 搜索文件和文件夹
• get_sharing_link: 创建共享链接
• get_file_content: 获取文件内容

账户操作

• get_account_info: 获取账户信息

使用示例

typescript // 列出根目录中的文件 await mcp.useTool("dbx-mcp-server", "list_files", { path: "" });

// 上传文件 await mcp.useTool("dbx-mcp-server", "upload_file", { path: "/test.txt", content: Buffer.from("Hello World").toString("base64"), });

// 搜索文件 await mcp.useTool("dbx-mcp-server", "search_file_db", { query: "report", path: "/Documents", max_results: 10, });

测试

运行测试套件：

bash npm test

测试验证所有操作，包括认证、文件操作和错误处理。

测试结构

测试套件被组织成几个模块：

• Dropbox操作: 对基本文件操作（上传、下载、列表等）的测试
• 账户操作: 对访问账户信息的测试- 搜索和删除：测试搜索功能和支持回收站的安全删除
• 资源系统：测试MCP资源系统集成

处理测试数据

测试使用基于时间戳动态生成的文件和文件夹名称，以避免冲突。测试数据在测试执行后会自动清理。

运行特定测试

要运行特定的测试文件或测试组：

bash npm test -- tests/dropbox/search-delete.test.ts # 运行特定的测试文件 npm test -- -t "should search for files" # 运行匹配描述的测试

测试故障排除

如果测试因时间或认证问题失败：

1. 检查tests/setup.ts中的模拟实现是否符合您的测试预期
2. 确保测试辅助工具正确配置
3. 对于Jest作用域错误，避免在模拟工厂函数中引用导入的变量

开发

构建所用技术栈：

• TypeScript
• Model Context Protocol SDK
• Dropbox SDK v10.34.0
• Dropbox API v2

许可证

MIT许可证

版权所有 (c) 2025 MCP Server 贡献者

在此授予任何人免费获得本软件及其相关文档文件（“软件”）副本的权利，可以不受限制地处理该软件，包括但不限于使用权、复制权、修改权、合并权、发布权、分发权、转授权以及/或者销售软件副本的权利，并允许向其提供软件的人也这样做，但需满足以下条件：

上述版权声明和此许可声明必须包含在所有软件副本或重要部分中。

本软件按“原样”提供，不附带任何形式的保证，无论是明示还是暗示，包括但不限于适销性、针对特定目的的适用性和非侵权性的保证。在任何情况下，作者或版权持有者均不对任何索赔、损害或其他责任负责，无论是在合同行为、侵权行为或其他情况下，由软件或软件的使用或其他交易引起或与之相关的。

软件。