Servidor MCP de Box

Descripción

El Servidor MCP de Box es un proyecto Python que se integra con la API de Box para realizar diversas operaciones como búsqueda de archivos, extracción de texto, consultas basadas en IA y extracción de datos. Aprovecha la librería box-sdk-gen y proporciona un conjunto de herramientas para interactuar con los archivos y carpetas de Box.

El Protocolo de Contexto de Modelos (MCP) es un marco diseñado para estandarizar la forma en que los modelos interactúan con diversas fuentes y servicios de datos. En este proyecto, MCP se utiliza para facilitar una integración perfecta con la API de Box, permitiendo operaciones eficientes y escalables en archivos y carpetas de Box. El proyecto Box MCP Server tiene como objetivo proporcionar una solución robusta y flexible para gestionar y procesar datos de Box utilizando técnicas avanzadas de IA y aprendizaje automático.

Herramientas implementadas

Herramientas API de Box

`box_who_am_i`

Obtiene la información del usuario actual y comprueba el estado de la conexión.

Devuelve: Cadena de información de usuario

`box_authorize_app_tool`

Inicia el proceso de autorización de la aplicación Box.

Devuelve: Mensaje de estado de autorización

`box_search_tool`

Buscar archivos en Box.

Parámetros
- query (str): La consulta a buscar.
- file_extensions (Lista[str], opcional): Extensiones de archivo para filtrar los resultados.
- where_to_look_for_query (Lista[str], opcional): Ubicaciones en las que buscar (por ejemplo, NAME, DESCRIPTION, FILE_CONTENT, COMMENTS, TAG).
- ancestor_folder_ids (Lista[str], opcional): Lista de ID de carpetas en las que buscar.
Devuelve: Los resultados de la búsqueda como una lista separada por nuevas líneas de nombres de archivo e IDs.

`box_read_tool`

Lee el contenido de texto de un archivo Box.

Parámetros:

file_id (str): ID del archivo a leer

Devuelve: Contenido del fichero

`box_ask_ai_tool`

Pregunta a Box AI sobre un fichero.

Parámetros:

file_id (str): ID del archivo
prompt (str): Pregunta para la IA

Devuelve: Respuesta de la IA

`box_hubs_preguntar_herramienta_ai`

Pregunta a la IA de Box sobre un hub. Actualmente no hay forma a través de la API de descubrir el ID de un hub, por lo que debe conocer el ID para utilizar esta herramienta. Arreglaremos esto en el futuro.

Parámetros:

hubs_id (str): ID del hub
prompt (str): Pregunta para la IA

Devuelve: Respuesta de la IA

`box_buscar_carpeta_por_nombre`

Localiza una carpeta por su nombre.

Parámetros:

nombre_carpeta (str): Nombre de la carpeta

Devuelve: ID de la carpeta

`box_ai_extraer_datos`

Extrae datos de un fichero utilizando AI.

Parámetros:

file_id (str): ID del archivo
fields (str): Campos a extraer

Devuelve: Datos extraídos en formato JSON

`box_list_folder_content_by_folder_id`

Lista el contenido de la carpeta.

Parámetros:

folder_id (str): ID de la carpeta
is_recursive (bool): Si listar recursivamente

Devuelve: Contenido de la carpeta en formato JSON con id, nombre, tipo y descripción

`box_manage_folder_tool`

Crea, actualiza o elimina carpetas en Box.

Parámetros:

action (str): Acción a realizar: "crear", "eliminar" o "actualizar"
folder_id (cadena, opcional): ID de la carpeta (obligatorio para eliminar/actualizar)
name (cadena, opcional): Nombre de la carpeta (obligatorio para crear, opcional para actualizar)
parent_id (cadena, opcional): ID de la carpeta padre (obligatorio para crear, opcional para actualizar)
description (cadena, opcional): Descripción de la carpeta (opcional para actualización)
recursive (bool, opcional): Si borrar recursivamente (opcional para delete)

Devuelve: Mensaje de estado con los detalles de la carpeta

`box_upload_file_tool`

=======

Parámetros
- file_id (str): El ID del archivo a leer.
Devuelve: Contenido en texto del fichero.

`box_ask_ai_tool`

Consulta a Box AI sobre un único archivo.

Parámetros
- file_id (str): El identificador del archivo.
- prompt (str): Consulta o instrucción para la IA.
Devuelve: Respuesta de la IA en función del contenido del fichero.

`box_ask_ai_tool_multi_file`

Consulta la IA de Box utilizando varios archivos.

Parámetros
- file_ids (Lista[str]): Lista de ID de archivos.
- prompt (str): Instrucción para la IA basada en el contenido agregado.
Devuelve: Respuesta generada por la IA considerando todos los ficheros proporcionados.

`box_buscar_carpeta_por_nombre`

Localiza una carpeta en Box por su nombre.

Parámetros
- nombre_carpeta (str): Nombre de la carpeta.
Devuelve: Información (nombre e ID) sobre las carpetas coincidentes.

`box_ai_extract_data`

Extrae campos específicos de un fichero utilizando AI.

Parámetros
- file_id (str): ID del archivo.
- fields (str): Lista separada por comas de los campos a extraer.
Devuelve: Los datos extraídos en formato de cadena JSON.

`box_list_folder_content_by_folder_id`

Lista el contenido de una carpeta utilizando su ID.

Parámetros
- folder_id (str): ID de carpeta.
- is_recursive (bool, opcional): Si listar el contenido recursivamente.
Devuelve: Contenido de la carpeta como una cadena JSON que incluye id, nombre, tipo y descripción.

`box_manage_folder_tool`

Crea, actualiza o elimina una carpeta en Box.

Parámetros
- action (str): Acción a realizar: "crear", "eliminar" o "actualizar".
- folder_id (cadena, opcional): ID de carpeta (obligatorio para eliminar y actualizar).
- name (cadena, opcional): Nombre de la carpeta (obligatorio para crear, opcional para actualizar).
- parent_id (cadena, opcional): ID de la carpeta padre (por defecto "0" para la raíz).
- description (cadena, opcional): Descripción de la carpeta (para actualización).
- recursive (bool, opcional): Para la eliminación recursiva.
Devuelve: Mensaje de estado con detalles de la carpeta.

`box_upload_file_from_path_tool`

Sube un archivo a Box desde una ruta del sistema de archivos local.

Parámetros
- ruta_archivo (str): Ruta del archivo local.
- folder_id (cadena, opcional): ID de la carpeta de destino (por defecto es "0").
- nombre_archivo_nuevo (cadena, opcional): Nuevo nombre de archivo (si no se indica, se utiliza el nombre de archivo original).
Devuelve: Detalles sobre el archivo cargado (ID y nombre) o un mensaje de error.

`box_upload_file_from_content_tool`

Sube contenido como un archivo a Box.

Parámetros
- content (str | bytes): Contenido a subir (texto o binario).
- nombre_archivo (str): El nombre a asignar al archivo.
- folder_id (str, opcional): ID de la carpeta de destino (por defecto es "0").
- is_base64 (bool, opcional): Indica si el contenido proporcionado está codificado en base64.
Devuelve: Mensaje de éxito de la subida con el ID y el nombre del archivo.

`box_download_file_tool`

Descarga un archivo desde Box.

Parámetros
- file_id (str): El ID del archivo a descargar.
- save_file (bool, opcional): Si desea guardar el archivo localmente.
- save_path (str, opcional): La ruta local donde debe guardarse el archivo.
Devuelve: Para archivos de texto, devuelve el contenido; para imágenes, devuelve datos codificados en base64; para otros tipos, un mensaje de error o de confirmación de guardado.

Herramientas Box Doc Gen

`box_docgen_create_batch_tool`

Genera documentos utilizando una plantilla de Box Doc Gen y un archivo JSON local.

Parámetros
- file_id (str): ID del archivo de plantilla.
- destination_folder_id (str): ID de la carpeta donde se almacenarán los documentos generados.
- user_input_file_path (str): Ruta a un archivo JSON con los datos de entrada.
- output_type (cadena, opcional): Formato de salida (por defecto es "pdf").
Devuelve: El resultado del lote de generación de documentos como cadena JSON.

`box_docgen_get_job_tool`

Obtiene un único trabajo Doc Gen por su ID.

Parámetros
- job_id (str): El identificador del trabajo.
Devuelve: Los detalles del trabajo en una cadena con formato JSON.

`box_docgen_list_jobs_tool`

Lista todos los trabajos Doc Gen asociados al usuario actual.

Parámetros
- marker (str | None, opcional): Marcador de paginación.
- limit (int | None, opcional): Número máximo de trabajos a devolver.
Devuelve: Lista paginada de trabajos en JSON con impresión bonita.

`box_docgen_list_jobs_by_batch_tool`

Lista los trabajos de Doc Gen pertenecientes a un lote específico.

Parámetros
- batch_id (str): El identificador del lote.
- marker (str | None, opcional): Marcador de paginación.
- limit (int | None, opcional): Número máximo de trabajos a devolver.
Devuelve: Detalles de los trabajos por lotes como JSON.

`box_docgen_plantilla_crear_herramienta`

Marca un archivo como plantilla de Box Doc Gen.

Parámetros
- file_id (str): ID del archivo a marcar como plantilla.
Devuelve: Detalles de la plantilla tras el marcado.

`box_docgen_plantilla_list_tool`

Lista todas las plantillas disponibles de Box Doc Gen.

Parámetros
- marker (str | None, opcional): Marcador de paginación.
- limit (int | None, opcional): Número máximo de plantillas a listar.
Devuelve: Lista de plantillas en formato JSON.

`box_docgen_template_delete_tool`

Elimina el marcado de plantillas Doc Gen de un fichero.

Parámetros
- template_id (str): El identificador de la plantilla.
Devuelve: La confirmación de la eliminación como JSON.

`box_docgen_template_get_by_id_tool`

Recupera detalles de una plantilla Doc Gen específica.

Parámetros
- template_id (str): El identificador de la plantilla.
Devuelve: Los detalles de la plantilla como JSON.

`box_docgen_template_list_tags_tool`

Lista todas las etiquetas asociadas a una plantilla Box Doc Gen.

Parámetros
- template_id (str): El ID de la plantilla.
- template_version_id (str | None, opcional): ID de la versión específica.
- marker (str | None, opcional): Marcador de paginación.
- limit (int | None, opcional): Número máximo de etiquetas a devolver.
Devuelve: Lista de etiquetas en formato JSON.

`box_docgen_template_list_jobs_tool`

Lista todos los trabajos de Doc Gen que usaron una plantilla específica.

Parámetros
- template_id (str): El identificador de la plantilla.
- marker (str | None, opcional): Marcador de paginación.
- limit (int | None, opcional): Número máximo de trabajos a listar.
Devuelve: Detalles del trabajo para la plantilla como una cadena JSON.

Requisitos

Python 3.13 o superior
Credenciales de Box API (ID de cliente, secreto de cliente, etc.)

Instalación

Clone el repositorio:

git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box

Instale uv si aún no está instalado:

2.1 MacOS+Linux

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

2.2 Windows

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

Crear y configurar nuestro proyecto:

3.1 MacOS+Linux

# Crear entorno virtual y activarlo uv venv source .venv/bin/activate # Bloquear las dependencias uv lock

3.2 Windows

# Crear entorno virtual y activarlo uv venv .venv\Scripts\activate # Bloquear las dependencias uv lock

Cree un archivo .env en el directorio raiz y añada sus credenciales API de Box:
```
BOX_CLIENT_ID=su_cliente_id BOX_CLIENT_SECRET=su_cliente_secreto
```

Uso

Ejecutar el servidor MCP

El servidor MCP soporta cuatro métodos de transporte: stdio (por defecto), SSE (Server-Sent Events), HTTP (StreamableHttp), y FastAPI.

Ejecución con transporte stdio (por defecto)

uv --directory /ruta/al/mcp-servidor-caja run src/mcp_servidor-caja.py

Utilizar Claude como cliente

Para transporte stdio (recomendado para Claude Desktop)

Edite su claude_desktop_config.json:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Añade la configuración

{ "mcpServers": { "mcp-server-box": { "command": "uv", "args": [ "--directory", "/path/to/mcp-server-box", "run", "src/mcp_server_box.py" ] } }

Reinicie Claude si se está ejecutando.

Usando Cursor como cliente

Para el transporte stdio

Abra su IDE con Cursor.
En ajustes, seleccione Ajustes de Cursor.
En el menú de la izquierda, seleccione MCP.
En la parte superior izquierda, haga clic en Añadir nuevo servidor MCP global.

Pegue el siguiente JSON (actualice para sus valores locales):

{ "mcpServers": { "box": { "command": "uv", "args": [ "--directory", "/path/to/mcp-server-box", "run", "src/mcp_server_box.py" ] } }

Guarde y cierre el archivo mcp.json, y reinicie si es necesario.

Ejecución de pruebas

El proyecto incluye un conjunto de pruebas para verificar la funcionalidad de la API de Box. Antes de ejecutar las pruebas, actualice los ID de archivo y carpeta de los archivos de prueba para que coincidan con los de su cuenta de Box.

Configuración de las pruebas

Actualizar IDs de archivos y carpetas
- Cada archivo de prueba (en el directorio tests/ ) utiliza IDs codificados para los archivos y carpetas de Box.
- Sustituya estos IDs por IDs válidos de su cuenta de Box.
Referencias de ID de archivos
- Por ejemplo, en tests/test_box_api_read.py, sustituya "1728677291168" por un ID de archivo válido.

Ejecución de pruebas

Una vez actualizados los ID, puede ejecutar las pruebas con pytest:

# Ejecutar todas las pruebas pytest Ejecutar un archivo de prueba específico pytest tests/test_box_api_file_ops.py Ejecutar pruebas con salida detallada pytest -v Ejecutar pruebas y mostrar declaraciones de impresión pytest -v -s

Solución de problemas

Si recibe el error Error: spawn uv ENOENT en MacOS al ejecutar el servidor MCP con Claude Desktop, puede:

Eliminar uv y volver a instalarlo con Homebrew: brew install uv

O proporcionar la ruta completa al ejecutable uv en su configuración:

/Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

[Asegúrese de que sus credenciales de la API de Box en .env están correctamente configuradas.

Servidor	Resumen	Acciones
Servidor MCP de AWS S3	Servidor MCP para operaciones de AWS S3, que proporciona acceso seguro a los buckets de S3 a través...	Ver
MCP de Dropbox	Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona integración con Dropbox, permit...	Ver
DropBin	No hay documentación disponible.	Ver
Servidor MCP WebDAV	Un servidor de Protocolo de Contexto de Modelo (MCP) que permite operaciones CRUD en un punto final...	Ver
Servidor OSS MCP	中文版 \| Español	Ver
Google Drive	Este servidor MCP se integra con Google Drive para permitir listar, leer y buscar archivos, así como...	Ver

Caja

Servidor MCP de Box

Descripción

Herramientas implementadas

Herramientas API de Box

box_who_am_i

box_authorize_app_tool

box_search_tool

box_read_tool

box_ask_ai_tool

box_hubs_preguntar_herramienta_ai

box_buscar_carpeta_por_nombre

box_ai_extraer_datos

box_list_folder_content_by_folder_id

box_manage_folder_tool

box_upload_file_tool

box_ask_ai_tool

box_ask_ai_tool_multi_file

box_buscar_carpeta_por_nombre

box_ai_extract_data

box_list_folder_content_by_folder_id

box_manage_folder_tool

box_upload_file_from_path_tool

box_upload_file_from_content_tool

box_download_file_tool

Herramientas Box Doc Gen

box_docgen_create_batch_tool

box_docgen_get_job_tool

box_docgen_list_jobs_tool

box_docgen_list_jobs_by_batch_tool

box_docgen_plantilla_crear_herramienta

box_docgen_plantilla_list_tool

box_docgen_template_delete_tool

box_docgen_template_get_by_id_tool

box_docgen_template_list_tags_tool

box_docgen_template_list_jobs_tool

Requisitos

Instalación

Uso

Ejecutar el servidor MCP

Ejecución con transporte stdio (por defecto)

Utilizar Claude como cliente

Para transporte stdio (recomendado para Claude Desktop)

Usando Cursor como cliente

Para el transporte stdio

Ejecución de pruebas

Configuración de las pruebas

Ejecución de pruebas

Solución de problemas

Relacionados en Almacenamiento en la nube - MCP Servers Seguros

`box_who_am_i`

`box_authorize_app_tool`

`box_search_tool`

`box_read_tool`

`box_ask_ai_tool`

`box_hubs_preguntar_herramienta_ai`

`box_buscar_carpeta_por_nombre`

`box_ai_extraer_datos`

`box_list_folder_content_by_folder_id`

`box_manage_folder_tool`

`box_upload_file_tool`

`box_ask_ai_tool`

`box_ask_ai_tool_multi_file`

`box_buscar_carpeta_por_nombre`

`box_ai_extract_data`

`box_list_folder_content_by_folder_id`

`box_manage_folder_tool`

`box_upload_file_from_path_tool`

`box_upload_file_from_content_tool`

`box_download_file_tool`

`box_docgen_create_batch_tool`

`box_docgen_get_job_tool`

`box_docgen_list_jobs_tool`

`box_docgen_list_jobs_by_batch_tool`

`box_docgen_plantilla_crear_herramienta`

`box_docgen_plantilla_list_tool`

`box_docgen_template_delete_tool`

`box_docgen_template_get_by_id_tool`

`box_docgen_template_list_tags_tool`

`box_docgen_template_list_jobs_tool`