dropbox-mcp

Сервер Model Context Protocol, который предоставляет LLM-агенту доступ на чтение и запись к аккаунту Dropbox — личному или Business/Team — через Dropbox API v2.

Проблема

Собственный настольный клиент Dropbox решает задачу синхронизации файлов. Но он не решает задачу контролируемого доступа агента к аккаунту, локальной копии которого у агента нет. Агент, который видит только синхронизированные папки, не может искать по командному архиву на 2 ТБ, не может создать общую ссылку и не может прочитать файл, который ему не был предоставлен.

Этот сервер закрывает этот разрыв. Он напрямую работает с Dropbox HTTP API, поэтому охватывает весь аккаунт, не синхронизируя на диск ни одного байта, и предоставляет этот доступ в виде фиксированного набора MCP-инструментов, а не сырого HTTP-клиента — агент получает dropbox_search, а не fetch.

Related MCP server: Dropbox MCP Server

Архитектура

Четыре модуля инструментов (files, search, sharing, account) регистрируются в одном McpServer, работающем по MCP через stdio. Каждый модуль проходит через единый HTTP-клиент, который отвечает за два раздражающих аспекта Dropbox API: жизненный цикл OAuth-токенов и корпоративное пространство имён. Модули можно отключать по отдельности при запуске через DROPBOX_DISABLED_MODULES, поэтому инсталляция, которая не должна создавать публичные общие ссылки, просто не регистрирует этот модуль, — возможность отсутствует, а не просто не рекомендуется.

  MCP host (Claude, etc.)
          | stdio (JSON-RPC)
  +-------v--------------------------------------+
  |  index.ts   module registry / stdio transport|
  +-------+--------------------------------------+
          |
  +-------v-------+ +--------+ +---------+ +---------+
  |  tools/files  | | search | | sharing | | account |
  +-------+-------+ +---+----+ +----+----+ +----+----+
          |             |           |           |
          +------+------+-----------+-----------+
                 |
        +--------v-----------------------------------+
        |  client.ts                                 |
        |   - refresh-token -> access-token cache     |
        |   - 401 retry with a forced refresh         |
        |   - Dropbox-API-Path-Root resolution        |
        |   - ASCII-safe Dropbox-API-Arg encoding     |
        +--------+-----------------------------------+
                 |
      RPC api.dropboxapi.com   Content content.dropboxapi.com

Два семейства конечных точек намеренно оставлены раздельными функциями: RPC-эндпоинты работают по принципу JSON-in/JSON-out, а Content-эндпоинты передают аргументы в HTTP-заголовке, используя тело для байтов файла. Сведение их в один обобщённый request() потребовало бы параметра, который незаметно меняет то, куда отправляются аргументы, поэтому они остаются раздельными.

Самая сложная часть

В командных аккаунтах Dropbox Business API по умолчанию работает с личным (home) пространством имён участника. Все командные папки — а именно там происходит настоящая совместная работа — находятся в корневом пространстве имён команды и просто не видны. list_folder на "" возвращает личные файлы участника и больше ничего, без ошибки и без намёка на то, что большая часть аккаунта отсутствует. Это выглядит как проблема прав доступа, но ею не является.

Решение — отправлять заголовок Dropbox-API-Path-Root, указывающий на корневое пространство имён команды, идентификатор которого получается из users/get_current_account. Это создаёт лвулку рекурсии: общий RPC-helper присоединяет заголовок path-root к каждому запросу, поэтому если он сам будет определять пространство имён через вызов get_current_account внутри себя, происходит определение заголовка через определение заголовка без конца. Поэтому resolveRootNamespaceId() отправляет намеренно пустой запрос через fetch, минуя helper, а результат мемоизируется, чтобы лишний туда-обратно происходил только один раз за процесс (src/client.ts).

Меньшая версия той же категории ошибки: Content-эндпоинты передают аргументы в Dropbox-API-Arg, а HTTP-заголовки — это ASCII. Файл с акцентным символом или эмодзи в имени вызовет ошибку внутри fetch, а не вернёт ошибку API. apiArg() преобразует каждый не-ASCII кодемический символ в \uXXXX перед тем, как заголовок будет собран.

Что бы я сделал иначе

1. Без тестов. Это было написано и проверено вручную на живом аккаунте. Путь обновления токена, повтор при 401 и границы чанковой загрузки — именно тот код, который должен был быть написан при помощи тестов с мопросом транспорта: они ломаются редко и дорого.

2. Кеш path-root является per-process и никогда не инвилидируется. Это нормально для stdio-сервера, который хост свободно перезапускает; но неправильно для долгоживущих систем, где пользователя могут перемещать между командами.

3. dropbox_delete не имеет механизма подтверждения. Наряду с вызовом серrophe Dropbox обеспечивает восстановление, но разрушительный инструмент должен демонстрировать это в своей схеме, а не полагаться на вопросы хоста.

4. Ошибки превращаются в строки. Возврат структурированного кода ошибки наряду с сообщением позволил бы агенту принимать решение по ветвям «rate limited» или «not found», не разбирая прозу.

Настройка

Требуются Node 20+ (разработано на 24) и аккаунт Dropbox.

1. Создайте приложение Dropbox

1. Перейдите на https://www.dropbox.com/developers/apps и выберите Create app.

2. Выберите Scoped access и Full Dropbox.

3. В разделе Permissions включите account_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write, sharing.read, sharing.write, затем нажмите Submit.

4. В разделе Settings скопируйте App key и App secret.

2. Сборка и авторизация

git clone <this-repo>
cd dropbox-mcp
npm install
npm run build

cp .env.example .env      # fill in DROPBOX_APP_KEY and DROPBOX_APP_SECRET
npm run auth              # prints DROPBOX_REFRESH_TOKEN — paste it into .env

npm run auth выводит URL согласия, принимает отправленный вами обратно код и обменивает его на refresh-токен. После этого сервер сам обменивает его на краткосрочные access-токены.

3. Регистрация в MCP-хосте

{
  "mcpServers": {
    "dropbox": {
      "command": "node",
      "args": ["/absolute/path/to/dropbox-mcp/dist/index.js"],
      "env": {
        "DROPBOX_APP_KEY": "your-app-key",
        "DROPBOX_APP_SECRET": "your-app-secret",
        "DROPBOX_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

Перезапустите хост и задайте ему вопрос, например: «Сколько места в моём Dropbox?».

Чтобы проверить сервер без хоста:

npm run inspect           # @modelcontextprotocol/inspector

Инструменты

files — dropbox_list_folder, dropbox_get_metadata, dropbox_create_folder, dropbox_move, dropbox_copy, dropbox_delete, dropbox_get_temporary_link, dropbox_read_file, dropbox_upload (автоматически разбивает большие файлы на чанки через сеансы загрузки).

search — dropbox_search по именам файлов и содержимому, во всём аккаунте или в конкретной папке.

sharing — dropbox_create_shared_link, dropbox_list_shared_links, dropbox_get_shared_link_metadata, dropbox_revoke_shared_link.

account — dropbox_get_current_account, dropbox_get_space_usage.

Конфигурация

Вся конфигурация задаётся переменными окружения; полный блок с описанием см. в .env.example, включая управление пространством имён (DROPBOX_PATH_ROOT), ограничение размера чтения (DROPBOX_MAX_READ_BYTES), размер чанка загрузки и заголовки имперсонации для командного приложения.

Лицензия

MIT — см. LICENSE.