dropbox-mcp

Un servidor Model Context Protocol que ofrece a un agente LLM acceso de lectura/escritura a una cuenta de Dropbox —personal o Business/Team— a través de la API v2 de Dropbox.

El problema

El cliente de escritorio de Dropbox resuelve la sincronización de archivos. No resuelve dar a un agente de IA acceso controlado a una cuenta de la que no tiene una copia local. Un agente que solo puede ver carpetas sincronizadas no puede buscar en un archivo de equipo de 2 TB, no puede crear un enlace de uso compartido y no puede leer un archivo que nunca recibió.

Este servidor cierra esa brecha. Habla directamente con la API HTTP de Dropbox, por lo que funciona contra toda la cuenta sin sincronizar un solo byte en disco, y expone ese acceso como un conjunto fijo de herramientas MCP en lugar de un cliente HTTP en bruto: el agente obtiene dropbox_search, no fetch.

Related MCP server: Dropbox MCP Server

Arquitectura

Cuatro módulos de herramientas (files, search, sharing, account) se registran contra un único McpServer que habla MCP mediante stdio. Todos los módulos pasan por un único cliente HTTP que se encarga de las dos cosas que la API de Dropbox hace complicadas: el ciclo de vida del token de OAuth y el espacio de nombres del equipo. Los módulos se pueden desactivar individualmente at startup mediante DROPBOX_DISABLED_MODULES, de modo que un despliegue que no debería poder crear enlaces públicos para compartir parece que no registrar el módulo: la capacidad no está, no se limita a desaconsejarse.

  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

Dos familias de endpoints, deliberadamente mantenidas como funciones separadas: los endpoints de tipo RPC son JSON de entrada/salida, mientras que los endpoints de tipo Content ponen sus argumentos en una cabecera HTTP y usan el cuerpo para los bytes del archivo. Hecirlas colapsar en un único request() genérico habría implicado un parámetro que cambia silenciosamente el lugar donde van los argumentos, así que se mantienen separadas.

La parte realmente difícil

En un equipo de Dropbox Business, la API usa por defecto el espacio de nombres home del miembro. Cada carpeta de equipo — que es donde está el trabajo compartido real — situación en el espacio de nombres root del equipo y simplemente es invisible. list_folder sobre "" devuelve únicamente los archivos privados del miembro, sin error y sin indicio de que la mayor parte de la cuenta falta. Pieces un problema de permisos, pero no lo es.

La solución es enviar una cabecera Dropbox-API-Path-Root que señale al espacio de nombres root del equipo, cuyo id se obtiene de users/get_current_account. Eso introduce una trampa de recursión: el helper RPC genérico añade la cabecera path-root a cada llamada, y resolverla llamando a get_current_account a través de sí mismo significa que la resolución de cabecera se llama a sí misma para siempre. resolveRootNamespaceId() emite por tanto una llamada fetch deliberadamente desnuda que evita el helper, y el resultado se guarda en memoria para que la llamada adicional no ocurra una vez por proceso (src/client.ts).

Una versión más pequeña de la misma clase de problema: los endpoints de Content-Type pasan sus argumentos en Dropbox-API-Arg, y las cabeceras HTTP son ASCII. Cualquier archivo con un carácter acentuado o con un emoji en su nombre provoca una excepción dentro de fetch en lugar de un error. apiArg() escapa todos los puntos de código no ASCII a \uXXXX antes de construir la cabecera.

Lo que haría diferente

1. Sin pruebas. Esto se construyó y verificó a mano contra una cuenta real. La ruta de renovación del token, el reintento de 401 y las condiciones del límite de subida por bloques son exactamente el tipo de código que se debe controlled by tests con un transporte simulado: son las partes que fallan raramente y de forma cara.

2. La caché de path-root es por proceso e nunca se invalida. Adecuada para un servidor stdio que un host reboot con libertad; incorrecta para cualquier proceso de larga vida en el que un usuario pueda moverse entre equipos.

3. dropbox_delete se expone sin ningún modo de confirmación. La retención propia de Dropbox permite recuperarla, pero una oferta destructiva debería signalarlo en su esquema en lugar de que el host tenga que preguntar.

4. Los errores se convierten en cadenas. Devolver además un código de error estructurado junto con el mensaje le permitiría a un agente ramificarse entre "límite de velocidad" y "no encontrado" sin tener que parsear la prosa.

Puesta en marcha

Requiere Node 20+ (desarrollado en Node 24) y una cuenta de Dropbox.

1. Crear una aplicación de Dropbox

1. Ve a https://www.dropbox.com/developers/apps y elige Crear app.

2. En Acceso elige Acceso por ámbitos y Acceso completo a Dropbox.

3. En Permisos, marca account_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write, sharing.read, sharing.write y luego Enviar.

4. En Configuración, copia la clave de la app y el secreto de la app.

2. Comppila y autoriza

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 imprime una URL de consentimiento, recibe el código que pegas y lo canjea por un token de actualización. El servidor uses a partir de ese momento canjearlo por tokens de acceso de corta duración.

3. Regístrate con un host 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"
      }
    }
  }
}

Reinicia el host y pregúntale algo como "¿Cuál es mi uso de espacio de Dropbox?".

Para probar el servidor sin un host:

npm run inspect           # @modelcontextprotocol/inspector

Herramientas

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 (divide automáticamente los archivos grandes en bloques mediante sesiones de subida).

search — dropbox_search en nombres de archivo y contenido, en toda la cuenta o acotada a una carpeta.

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.

Configuración

Todos los ajustes se realizan por variables de entorno; consulta .env.example para la lista completa comentada, incluyendo el control de namespace (DROPBOX_PATH_ROOT), el límite de tamaño de lectura (DROPBOX_MAX_READ_BYTES), el tamaño de bloque de subida y las cabeceras de suplantación de la aplicación del equipo.

Licencia

MIT — ver LICENSE.