Dropbox

Dropbox MCP 服务

一个用 Go 编写的 Dropbox 集成模型上下文协议（MCP）服务实现。该服务允许 Claude 等 AI 助手通过标准化协议与 Dropbox 交互。

功能

• OAuth 2.0 身份验证：通过基于浏览器的 OAuth 流程安全地使用 Dropbox 身份验证
• 文件操作：列出、搜索、下载、上传、移动、复制和删除文件
• 文件夹管理：创建文件夹并浏览目录结构
• 共享：创建、列出和撤销共享链接
• 版本控制：查看文件修订历史记录并恢复以前的版本
• 大文件支持：自动分块上传超过 150 MB 的文件

前提条件

• Dropbox 账户
• Claude 桌面应用
• Go 1.21 或更高版本（仅从源代码构建时需要）

安装

选项 1：使用 Homebrew 安装（macOS/Linux）

brew tap ngs/tap
brew install dropbox-mcp-server

选项 2：使用 Go 安装

go install go.ngs.io/dropbox-mcp-server@latest

选项 3：下载预构建的二进制文件

从 releases page 下载适用于你平台的最新版本。

# Example for macOS (Apple Silicon)
curl -L https://github.com/ngs/dropbox-mcp-server/releases/latest/download/dropbox-mcp-server_darwin_arm64.tar.gz | tar xz
sudo mv dropbox-mcp-server /usr/local/bin/

# Example for macOS (Intel)
curl -L https://github.com/ngs/dropbox-mcp-server/releases/latest/download/dropbox-mcp-server_darwin_amd64.tar.gz | tar xz
sudo mv dropbox-mcp-server /usr/local/bin/

# Example for Linux (x86_64)
curl -L https://github.com/ngs/dropbox-mcp-server/releases/latest/download/dropbox-mcp-server_linux_amd64.tar.gz | tar xz
sudo mv dropbox-mcp-server /usr/local/bin/

选项 4：从源代码构建

git clone https://github.com/ngs/dropbox-mcp-server.git
cd dropbox-mcp-server
go build -o dropbox-mcp-server

设置

⚠️ 安全提示

重要：每位用户都必须创建自己的 Dropbox App。切勿在二进制文件中共享或嵌入 CLIENT_SECRET。详情请参阅 SECURITY.md。

1. 创建 Dropbox App

1. 前往 Dropbox App Console
2. 点击“Create app”
3. 选择配置：
   • Choose an API：选择“Scoped access”
   • Choose the type of access：根据需要选择“Full Dropbox”或“App folder”
   • Name your app：为你的 App 输入一个唯一名称
4. 创建后，前往该 App 的设置页面
5. 在“OAuth 2”下，添加重定向 URI：http://localhost:8080/callback
6. 记下你的 App key（Client ID）和 App secret（Client Secret）
7. 在“Permissions”选项卡中，确保已选择以下权限范围：
   • files.content.read - 查看 Dropbox 文件和文件夹的内容
   • files.content.write - 编辑 Dropbox 文件和文件夹的内容
   • files.metadata.read - 查看 Dropbox 文件和文件夹的信息
   • files.metadata.write - 查看和编辑 Dropbox 文件和文件夹的信息
   • sharing.read - 查看共享的文件和文件夹
   • sharing.write - 创建和修改共享的文件和文件夹

2. 配置 Claude 桌面应用

选项 A：使用 Claude MCP CLI（推荐）

如果已安装 Claude MCP CLI，可以通过一条命令注册服务：

# Basic registration (replace with YOUR OWN App credentials)
claude mcp add dropbox dropbox-mcp-server \
  --env DROPBOX_CLIENT_ID=your_own_app_key \
  --env DROPBOX_CLIENT_SECRET=your_own_app_secret

# With custom binary path
claude mcp add dropbox /path/to/dropbox-mcp-server \
  --env DROPBOX_CLIENT_ID=your_own_app_key \
  --env DROPBOX_CLIENT_SECRET=your_own_app_secret

⚠️ 安全提示：请使用你自己的 Dropbox App 凭据。切勿使用共享凭据。

选项 B：手动配置

将以下内容添加到 Claude 桌面应用配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dropbox": {
      "command": "dropbox-mcp-server",
      "env": {
        "DROPBOX_CLIENT_ID": "your_app_key_here",
        "DROPBOX_CLIENT_SECRET": "your_app_secret_here"
      }
    }
  }
}

注意：

• 如果通过 Homebrew 安装，或将二进制文件放在 /usr/local/bin 中，只需使用 "command": "dropbox-mcp-server"
• 如果从源代码构建，或下载到自定义位置，请使用完整路径："command": "/path/to/dropbox-mcp-server"

3. 验证安装

配置完成后，重启 Claude 桌面应用并确认服务已连接：

# List registered MCP servers (if using Claude MCP CLI)
claude mcp list

# Remove a server if needed
claude mcp remove dropbox

用法

初始身份验证

首次在 Claude 中使用 Dropbox MCP 服务时：

1. 使用 dropbox_auth 工具进行身份验证
2. 浏览器将打开 Dropbox 授权页面
3. 登录并授权该 App
4. 系统会将你重定向到成功页面
5. 身份验证令牌将保存到 ~/.dropbox-mcp-server/config.json

可用工具

身份验证

• dropbox_auth - 使用 Dropbox 进行身份验证
• dropbox_check_auth - 检查身份验证状态

文件操作

• dropbox_list - 列出文件和文件夹
• dropbox_search - 搜索文件
• dropbox_get_metadata - 获取文件／文件夹元数据
• dropbox_download - 下载文件内容
• dropbox_upload - 上传文件
• dropbox_create_folder - 创建新文件夹
• dropbox_move - 移动或重命名文件／文件夹
• dropbox_copy - 复制文件／文件夹
• dropbox_delete - 删除文件／文件夹

共享

• dropbox_create_shared_link - 创建共享链接
• dropbox_list_shared_links - 列出已有共享链接
• dropbox_revoke_shared_link - 撤销共享链接

版本控制

• dropbox_get_revisions - 获取文件修订历史
• dropbox_restore_file - 将文件恢复到之前的版本

Claude 中的示例命令

"Please authenticate with Dropbox"
"List all files in my Dropbox root folder"
"Search for PDF files containing 'invoice'"
"Upload this text to /Documents/notes.txt"
"Create a shared link for /Photos/vacation.jpg"
"Show me the revision history of /Documents/report.docx"

配置

服务会将配置存储在 ~/.dropbox-mcp-server/config.json 中：

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "access_token": "your_access_token",
  "refresh_token": "your_refresh_token",
  "expires_at": "2024-01-01T00:00:00Z"
}

令牌过期后会自动刷新。

安全注意事项

• 配置文件包含敏感令牌，并以 0600 权限存储
• 可以通过环境变量提供客户端凭据，无需写入配置文件
• OAuth 流程使用 state 参数来防止 CSRF 攻击
• 所有 API 调用均使用 HTTPS

故障排查

身份验证问题

• 确保在 Dropbox App Console 中正确配置了重定向 URI
• 检查客户端 ID 和密钥是否正确
• 尝试删除 ~/.dropbox-mcp-server/config.json 并重新进行身份验证

权限错误

• 确认你的 Dropbox 应用已启用所需的权限范围
• 检查文件路径是否正确（使用正斜杠，并以 / 开头）

连接问题

• 确保网络连接正常
• 检查你的网络是否可以访问 Dropbox API
• 查看 stderr 输出，获取详细错误信息

开发

从源代码构建

go mod download
go build -o dropbox-mcp-server

运行测试

go test ./...

项目结构

dropbox-mcp-server/
├── main.go                 # MCP server implementation
├── go.mod                  # Go module definition
├── internal/
│   ├── auth/              # OAuth authentication
│   ├── config/            # Configuration management
│   ├── dropbox/           # Dropbox API client
│   └── handlers/          # MCP tool handlers
├── mcp.json               # MCP server metadata
└── README.md              # This file

参与贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT License - 详情请参阅 LICENSE 文件

支持

如有问题或疑问，请在 GitHub 上提交 issue。