dbx-mcp-server

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

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

目录

• 快速开始
• 安装
• 认证
• 可用工具
• 所需的Dropbox权限
• 使用示例
• 开发
• 许可

快速开始

1. 克隆仓库
2. 运行 npm install 安装依赖
3. 运行 npm run build 构建项目
4. 运行 npm run setup
5. 配置您的MCP客户端以使用该服务器

前提条件

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

• 选择“范围访问”API
• 选择您应用需要的访问类型
• 命名您的应用并点击“创建应用”
• 在“权限”下，选择您将使用的操作所需的权限，例如：
  • files.metadata.read
  • files.content.read
  • files.content.write
  • sharing.write
  • account_info.read
• 添加 http://localhost 作为您的重定向URI
• 记住您的App key和App secret

安装

1. 克隆仓库

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

2. 安装依赖并构建

   npm install
   npm run build
   

3. 运行设置脚本

   npm run setup
   

4. 添加到MCP设置

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

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

认证

服务器使用OAuth 2.0和PKCE进行与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: 刷新尝试之间的延迟（毫秒，默认：11000）

可用工具

文件操作

• 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: 获取账户信息

所需的Dropbox权限

以下是服务器操作与所需的最小Dropbox OAuth范围（权限）的映射：

服务器操作	所需的Dropbox范围
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

额外的范围（如果需要）：

• sharing.read: 查看共享设置和协作者
• file_requests.read / file_requests.write: 用于文件请求功能
• contacts.read / contacts.write: 用于访问Dropbox联系人

有关Dropbox范围的更多详情，请参阅Dropbox权限文档。

使用示例

// 列出根目录中的文件
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: "报告",
  path: "/文档",
  max_results: 10,
});

开发

构建于：

• TypeScript
• 模型上下文协议SDK
• Dropbox SDK v10.34.0
• Dropbox API v2

许可

MIT许可

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

在此授权任何人免费获得此软件及其相关文档文件（以下简称“软件”），不受限制地处理软件，包括但不限于以下权利：

• 使用、复制、修改、合并、发布、分发、再许可和/或销售软件副本的权利
• 向接收软件的人提供上述权利，但须遵守以下条件：

以上版权声明和本许可通知应包含在软件的所有副本或主要部分中。

软件按“原样”提供，不附带任何形式的保证，包括但不限于适销性、特定用途适用性和非侵权性的默示保证。在任何情况下，作者或版权持有人都不对因软件或其使用或其他交易而产生的任何索赔、损害或其他责任承担任何责任，无论是合同行为、侵权行为还是其他行为引起的。