dbx-mcp-server

dbx-mcp-server

一个 Model Context Protocol (MCP) 服务，可集成 Dropbox，让兼容 MCP 的客户端通过一系列强大的工具与 Dropbox 交互。

**重要免责声明：**本项目与 Dropbox 无关，也未获其认可或赞助。这是一个独立集成，通过 Dropbox 的公开 API 提供服务。

目录

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

快速开始

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

前提条件

在 Dropbox App Console 注册一个 Dropbox 应用：

• 选择“Scoped access” API
• 选择应用所需的访问类型
• 为应用命名，然后点击“Create app”
• 在“Permissions”下，选择要使用的操作所需的权限，例如：
  • 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 应用的密钥
• DROPBOX_APP_SECRET：Dropbox 应用的密钥
• 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：获取账户信息

所需的 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 权限文档。

使用示例

// List files in root directory
await mcp.useTool("dbx-mcp-server", "list_files", { path: "" });

// Upload a file
await mcp.useTool("dbx-mcp-server", "upload_file", {
  path: "/test.txt",
  content: Buffer.from("Hello World").toString("base64"),
});

// Search for files
await mcp.useTool("dbx-mcp-server", "search_file_db", {
  query: "report",
  path: "/Documents",
  max_results: 10,
});

开发

使用以下技术构建：

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

许可证

MIT 许可证

版权所有 (c) 2025 MCP Server Contributors

特此免费授予任何获得本软件及相关文档文件（以下简称“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售本软件副本的权利，并允许获得本软件的人这样做，但须满足以下条件：

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

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