dbx-mcp-服务器

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

**重要免责声明：**本项目与 Dropbox 并无关联，亦未获得其认可或赞助。它是一个独立的集成项目，可与 Dropbox 的公共 API 配合使用。

快速入门

克隆存储库
运行npm install来安装依赖项
运行npm run build来构建项目
在Dropbox App Console注册一个 Dropbox 应用：
- 选择“范围访问”API
- 选择您的应用所需的访问类型
- 为您的应用命名并点击“创建应用”
- 在“权限”下，选择所需的权限：
  - files.metadata.read
  - files.content.read
  - files.content.write
  - sharing.write
  - account_info.read
- 添加http://localhost:3000/callback作为重定向 URI
- 记下您的 App key 和 App secret
运行安装脚本：
npm run setup
配置您的 MCP 客户端以使用服务器

安装

克隆存储库
git clone https://github.com/your-username/dbx-mcp-server.git cd dbx-mcp-server
安装依赖项并构建
npm install npm run build
运行安装脚本
npm run setup
添加到 MCP 设置将以下内容添加到您的 MCP 设置文件：
{ "mcpServers": { "dbx": { "command": "node", "args": ["/path/to/dbx-mcp-server/build/index.js"] } } }

验证

服务器使用带有 PKCE 的 OAuth 2.0 与 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 ：获取帐户信息

使用示例

// 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,
});

测试

运行测试套件：

npm test

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

测试结构

测试套件分为几个模块：

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

处理测试数据

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

运行特定测试

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

npm test -- tests/dropbox/search-delete.test.ts  # Run specific test file
npm test -- -t "should search for files"        # Run tests matching description

故障排除测试

如果测试因时间或身份验证问题而失败：

检查tests/setup.ts中的模拟实现是否符合你的测试预期
确保测试助手配置正确
对于 Jest 范围错误，避免在模拟工厂函数中引用导入的变量

发展

内置：

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

执照

MIT 许可证

特此授予获得此软件和相关文档文件（“软件”）副本的任何人免费许可，以无限制方式处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再授权和/或销售软件副本的权利，并允许向其提供软件的人员这样做，但须遵守以下条件：

Dropbox MCP Server

Integrations