MCP Server Box

说明

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

模型上下文协议（MCP）是一个旨在标准化模型与各种数据源和服务交互方式的框架。在这个项目中，MCP 用于促进与 Box API 的无缝集成，从而实现对 Box 文件和文件夹的高效和可扩展操作。MCP Server Box 项目旨在通过使用先进的 AI 和机器学习技术，为管理和处理 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、name、type 和 description

box_manage_folder_tool

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

参数：

• action (str): 要执行的操作："create"、"delete" 或 "update"
• 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 (Any, 可选): 上传到的文件夹ID

返回: 包含文件ID和名称的上传状态

box_download_file_tool

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

参数:

• file_id (Any): 要下载的文件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

   # 创建虚拟环境并激活它
   uv venv
   source .venv/bin/activate
   
   # 锁定依赖项
   uv lock
   

   3.2 Windows

   # 创建虚拟环境并激活它
   uv venv
   .venv\Scripts\activate
   
   # 锁定依赖项
   uv lock
   

4. 在根目录下创建一个.env文件，并添加您的Box API凭证：

   BOX_CLIENT_ID=your_client_id
   BOX_CLIENT_SECRET=your_client_secret
   

使用

运行MCP服务器

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

uv --directory /Users/anovotny/Desktop/mcp-server-box run src/mcp_server_box.py

使用Claude作为客户端

1. 编辑你的claude_desktop_config.json

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

1. 并添加以下内容：

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

[!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

1. 如果Claude正在运行，请重启它

使用Cursor作为客户端

1. 用Cursor打开你的IDE

2. 在设置中选择Cursor settings。

3. 在左侧导航栏中选择MCP。

4. 在左上角选择Add new global MCP server。

5. 粘贴以下json，并确保更新为你的本地值：

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

1. 保存并关闭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: 需要一个用于测试AI提取功能的文件ID
   • 其他测试文件可能需要特定的文件夹ID或文件类型

运行测试

一旦您更新了文件ID，您可以使用pytest运行测试：

# Run all tests
pytest

# Run a specific test file
pytest tests/test_box_api_file_ops.py

# Run tests with detailed output
pytest -v

# Run tests and show print statements
pytest -v -s

可用测试

• 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 fixture 进行认证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