MCP 服务器盒

描述

MCP Server Box 是一个 Python 项目，它集成了 Box API，可以执行各种操作，例如文件搜索、文本提取、基于 AI 的查询和数据提取。它利用box-sdk-gen库，并提供了一组与 Box 文件和文件夹交互的工具。

模型上下文协议 (MCP) 是一个框架，旨在标准化模型与各种数据源和服务的交互方式。在本项目中，MCP 用于促进与 Box API 的无缝集成，从而实现对 Box 文件和文件夹的高效且可扩展的操作。MCP 服务器 Box 项目旨在提供一个强大而灵活的解决方案，使用先进的人工智能和机器学习技术来管理和处理 Box 数据。

实施的工具

盒子工具

box_who_am_i

获取当前用户信息并检查连接状态。

**返回：**用户信息字符串

box_authorize_app_tool

启动 Box 应用程序授权流程。

**返回：**授权状态消息

box_search_tool

在 Box 中搜索文件。

参数：

• query （str）：搜索查询
• file_extensions (List[str]，可选)：要过滤的文件扩展名
• where_to_look_for_query (List[str]，可选)：搜索位置（NAME、DESCRIPTION、FILE_CONTENT、COMMENTS、TAG）
• ancestor_folder_ids (List[str]，可选)：要搜索的文件夹 ID

**返回：**搜索结果

box_read_tool

读取 Box 文件的文本内容。

参数：

• file_id (str): 要读取的文件的 ID

**返回：**文件内容

box_ask_ai_tool

向 Box AI 询问文件。

参数：

• file_id (str): 文件的ID
• prompt (str): 向 AI 提问

返回： AI响应

box_search_folder_by_name

通过名称找到文件夹。

参数：

• folder_name (str): 文件夹的名称

**返回：**文件夹 ID

box_ai_extract_data

使用 AI 从文件中提取数据。

参数：

• file_id (str): 文件的ID
• fields （str）：要提取的字段

**返回：**以 JSON 格式提取的数据

box_list_folder_content_by_folder_id

列出文件夹内容。

参数：

• folder_id (str): 文件夹的 ID
• is_recursive (bool): 是否递归列出

返回： JSON 格式的文件夹内容，包含 ID、名称、类型和描述

box_manage_folder_tool

在 Box 中创建、更新或删除文件夹。

参数：

• action (str): 要执行的操作：“创建”、“删除”或“更新”
• folder_id (str，可选)：文件夹的 ID（删除/更新时必需）
• name (str，可选)：文件夹名称（创建时必需，更新时可选）
• parent_id (str, 可选)：父文件夹 ID（创建时必需，更新时可选）
• description （str，可选）：文件夹描述（更新时可选）
• recursive （bool，可选）：是否递归删除（删除时可选）

**返回：**带有文件夹详细信息的状态消息

box_upload_file_tool

将内容作为文件上传到 Box。

参数：

• content （str）：作为文件上传的内容
• file_name (str): Box 中文件的名称
• folder_id （任意，可选）：要上传到的文件夹的 ID

**返回：**带有文件 ID 和名称的上传状态

box_download_file_tool

从 Box 下载文件并返回其内容。

参数：

• file_id （任意）：要下载的文件的 ID
• save_file (bool, 可选): 是否在本地保存文件
• save_path （str，可选）：保存文件的路径

**返回：**文件内容为文本、base64 编码图像或保存状态消息

要求

• Python 3.13 或更高版本
• Box API 凭证（客户端 ID、客户端密钥等）

安装

1. 克隆存储库：
   git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box
2. 如果尚未安装uv ，请安装：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"
3. 创建并设置我们的项目：3.1 MacOS+Linux
   # Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock
   3.1 Windows
   # Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock
4. 在根目录中创建一个.env文件并添加您的 Box API 凭证：
   BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret

用法

运行 MCP 服务器

要启动 MCP 服务器，请运行以下命令：

使用克劳德作为客户

1. 编辑你的claude_desktop_config

2. 并添加以下内容：

[!NOTE] 如果使用 MacOS，您需要使用 brew 安装 uv： brew install uv或提供 uv 可执行文件的完整路径： /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

3. 如果 Claude 正在运行，请重新启动

使用 Cursor 作为客户端

1. 使用 Cursor 打开 IDE
2. 在设置中，选择Cursor settings 。
3. 在左侧导航中，选择MCP 。
4. 在左上角，选择Add new global MCP server 。
5. 传递以下 json，确保更新您的本地值：

6. 保存并关闭 mcp.json 文件，并确保 MCP 服务器已启用。您可能需要重启。

运行测试

该项目包含一套测试，用于验证 Box API 的功能。在运行测试之前，您需要更新测试文件中的文件和文件夹 ID，使其与您 Box 帐户中的文件匹配。

设置测试

1. 更新文件和文件夹 ID ：
   • 每个测试文件（在tests/目录中）都包含 Box 文件和文件夹的硬编码 ID
   • 您需要将这些 ID 替换为您的 Box 帐户中的文件和文件夹的 ID
   • 示例：在test_box_api_read.py中，将"1728677291168"替换为您的 Box 帐户中的文件 ID
2. 测试文件ID参考：
   • test_box_api_read.py ：需要有效的文档文件 ID（例如 Word 文档）
   • test_box_api_search.py ：更新搜索查询和文件扩展名以匹配您的内容
   • test_box_api_ai.py ：需要文件 ID 来测试 AI 提取功能
   • 其他测试文件可能需要特定的文件夹 ID 或文件类型

运行测试

更新文件 ID 后，即可使用 pytest 运行测试：

可用测试

• test_box_auth.py ：测试身份验证功能
• test_box_api_basic.py ：基本 Box API 测试
• test_box_api_read.py ：测试文件读取功能
• test_box_api_search.py ：测试搜索功能
• test_box_api_ai.py ：测试基于AI的功能
• test_box_api_file_ops.py ：测试文件上传和下载操作

创建新测试

创建新测试时：

1. 遵循现有测试文件中的模式
2. 使用box_client装置进行经过身份验证的 API 访问
3. 清理测试期间创建的所有测试文件或文件夹
4. 添加适当的断言来验证功能

故障排除

如果您在 MacOS 上并使用 Claude Desktop 运行 MCP 服务器，则会看到以下错误：

Error: spawn uv ENOENT

您可以删除 uv 并使用 brew 重新安装： brew install uv或者提供 uv 可执行文件的完整路径： /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py