mcp-dropbox

<div align="center"> <img src="mcp_dropbox.png" alt="MCP Dropbox Logo" width="300" /> </div> <br>

Servidor MCP (Model Context Protocol) construido con FastMCP para recibir documentos desde un agente (por ejemplo, un agente de OpenAI) y guardarlos en dropbox. El proyecto está pensado como un Remote MCP Server: simple, mantenible y escalable.

Descripción

Este MCP expone herramientas (tools) que un agente puede invocar de forma remota.

Tools de Dropbox disponibles

Tool	Descripción	Parámetros
create_folder	Crea una carpeta en Dropbox (idempotente: si ya existe, no falla).	path: str, folder_name: str
folder_exists	Verifica si una carpeta existe en una ruta dada.	path: str, folder_name: str
delete_folder	Borra el contenido (subcarpetas) de un directorio.	directory_path: str
create_shared_link_file	Crea o recupera un enlace público para un archivo o carpeta.	path: str, expires_days: Optional[int], password: Optional[str], access_level: str, folder_settings: Optional[dict]
upload_file	Sube un archivo local a Dropbox (con soporte de sesiones para archivos >150MB).	path_local_file: str, remote_file_upload: str
list_directories	Lista las subcarpetas de una ruta (no recursivo).	path: str
list_files	Lista los archivos de una ruta (no recursivo).	path: str
upload_file_binario	Recibe un archivo en base64, lo guarda en HD_DESCARGAS/ y lo sube a Dropbox en segundo plano (vía process_upload.py).	nombre_archivo: str, contenido_base64: str, dropbox_path: str

upload_file_binario acepta dos variables de entorno opcionales para lanzar el subproceso: _APP_PATH_ (raíz del proyecto; por defecto se detecta automáticamente) y _PYTHON_APP_ (intérprete de Python; por defecto el mismo que ejecuta el servidor).

Cada tool documenta sus parámetros y valores de retorno en su propio docstring; para verlos vía CLI:

uv run fastmcp list http://127.0.0.1:8000/mcp --auth mi-token-secreto-dropbox --input-schema

Requisitos

• Python 3.13+
• uv

Instalación de uv

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verifica la instalación con:

uv --version

Crear el entorno virtual

uv venv

Activar el entorno:

• macOS / Linux: source .venv/bin/activate
• Windows: .venv\Scripts\activate

Instalar dependencias (pyproject.toml)

Con el entorno virtual activo, instala las dependencias declaradas en pyproject.toml:

uv sync

Autenticación

El servidor exige un token Bearer para todas las peticiones. El token válido se define mediante la variable de entorno MCP_AUTH_TOKEN (no se hardcodea en el código) MCP_AUTH_TOKEN es el token con los permisos nesesario en dropbox.

Para levantar el servidor con autenticación activada:

MCP_AUTH_TOKEN=mi-token-secreto-dropbox uv run python3 main.py

Variables opcionales:

• MCP_HOST (por defecto 0.0.0.0)
• MCP_PORT (por defecto 8000)
• MCP_ALLOWED_HOSTS: dominios permitidos en el header Host (separados por coma). Necesario cuando expones el servidor a través de un túnel (ngrok, cloudflared) o dominio propio; de lo contrario el servidor responde 421 Misdirected Request, ya que por seguridad solo acepta localhost/127.0.0.1 por defecto. Ejemplo: MCP_ALLOWED_HOSTS=*.ngrok-free.app o MCP_ALLOWED_HOSTS=mi-tunel.ngrok-free.app

Cualquier cliente (incluido el agente) debe enviar el header:

Authorization: Bearer mi-token-secreto-dropbox

Ejecutar el servidor

MCP_AUTH_TOKEN=mi-token-secreto-dropbox uv run python3 main.py

Esto levanta el servidor en http://0.0.0.0:8000/mcp (o el MCP_PORT que definas).

Según cómo quieras dejarlo corriendo:

1. Primer plano (para probar): el comando de arriba tal cual; se detiene con Ctrl+C.
2. En segundo plano: agrega & al final, o usa nohup ... & para que sobreviva si cierras la terminal.
3. Como servicio persistente (recomendado si un agente debe conectarse en todo momento): usa algo que lo mantenga vivo y lo reinicie si falla, por ejemplo un launchd plist en macOS, o Docker/systemd en un servidor Linux.
4. Accesible desde internet: como corre en 0.0.0.0, localmente solo es alcanzable en tu red. Para exponerlo a un agente remoto (por ejemplo un agente de OpenAI) necesitas un túnel (ngrok, cloudflared) mientras pruebas, o desplegarlo en un servidor/VPS con IP pública para producción.

Ver la documentación de las tools disponibles

El endpoint /mcp no es una API REST navegable (no muestra una página de documentación en el navegador): es un endpoint JSON-RPC que espera peticiones POST con headers específicos. Además, si accedes usando http://0.0.0.0:8000/mcp verás el error "Misdirected Request" (421), ya que 0.0.0.0 solo indica en qué interfaces escucha el servidor, no es una dirección válida para conectarte: usa http://127.0.0.1:8000/mcp o http://localhost:8000/mcp en su lugar.

Para listar las tools disponibles y su esquema, usa la CLI de FastMCP:

uv run fastmcp list http://127.0.0.1:8000/mcp --auth mi-token-secreto-dropbox --input-schema

Inspector visual (MCP Inspector)

Para explorar y probar las tools desde una interfaz web interactiva, usa el MCP Inspector (requiere Node.js/npx instalado). No necesitas tener el servidor corriendo por separado: el propio comando lo levanta.

MCP_AUTH_TOKEN=mi-token-secreto-dropbox uv run fastmcp dev inspector main.py

Esto abre automáticamente el navegador en una URL tipo http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=..., donde puedes ver las tools disponibles, sus esquemas y ejecutarlas manualmente con distintos parámetros.

Despliegue en Producción (Ubuntu 24.04)

Para entornos de producción (por ejemplo, en un VPS con Ubuntu 24.04 y un dominio como mcp.dominio.com), se incluye un archivo de configuración de systemd (mcp-dropbox.service).

1. Sube tu código al servidor, por ejemplo a /var/www/mcp_dropbox.

2. Asegúrate de instalar uv en el servidor y ejecuta uv sync en la carpeta del proyecto.

3. Configura el token (Archivo .env): Crea un archivo .env en la ruta de tu proyecto para mantener seguro el token:

   sudo nano /var/www/mcp_dropbox/.env
   

   Agrega la siguiente línea:

   MCP_AUTH_TOKEN=aqui-tu-token-super-seguro-dropbox
   

4. Instala y habilita el servicio de systemd: Asegúrate de que las rutas y el usuario en mcp-dropbox.service coincidan con tu servidor, luego ejecuta:

   sudo cp /var/www/mcp_dropbox/mcp-dropbox.service /etc/systemd/system/mcp-dropbox.service
   sudo systemctl daemon-reload
   sudo systemctl enable mcp-dropbox
   sudo systemctl start mcp-dropbox
   

5. Verifica el estado del servicio:

   sudo systemctl status mcp-dropbox
   

Nota: Necesitarás configurar un proxy inverso (como Nginx o Caddy) en el servidor para redirigir el tráfico de tu dominio (mcp.dominio.com) en los puertos 80/443 hacia el servicio interno en http://127.0.0.1:8000.

Licencia

Este proyecto se distribuye bajo una licencia de uso No Comercial. Permite su uso libre para fines personales, académicos o de investigación, pero prohíbe cualquier uso comercial o corporativo sin autorización previa. Ver LICENSE para más detalles.