MCP Server Box

Description

MCP Server Box is a Python project that integrates with the Box API to perform various operations such as file search, text extraction, AI-based querying, and data extraction. It leverages the box-sdk-gen library and provides a set of tools to interact with Box files and folders.

The Model Context Protocol (MCP) is a framework designed to standardize the way models interact with various data sources and services. In this project, MCP is used to facilitate seamless integration with the Box API, enabling efficient and scalable operations on Box files and folders. The MCP Server Box project aims to provide a robust and flexible solution for managing and processing Box data using advanced AI and machine learning techniques.

Tools implemented

Box Tools

`box_who_am_i`

Get your current user information and check connection status.

Returns: User information string

`box_authorize_app_tool`

Start the Box application authorization process.

Returns: Authorization status message

`box_search_tool`

Search for files in Box.

Parameters:

query (str): Search query
file_extensions (List[str], optional): File extensions to filter by
where_to_look_for_query (List[str], optional): Where to search (NAME, DESCRIPTION, FILE_CONTENT, COMMENTS, TAG)
ancestor_folder_ids (List[str], optional): Folder IDs to search within

Returns: Search results

`box_read_tool`

Read the text content of a Box file.

Parameters:

file_id (str): ID of the file to read

Returns: File content

`box_ask_ai_tool`

Ask Box AI about a file.

Parameters:

file_id (str): ID of the file
prompt (str): Question for the AI

Returns: AI response

`box_search_folder_by_name`

Locate a folder by name.

Parameters:

folder_name (str): Name of the folder

Returns: Folder ID

`box_ai_extract_data`

Extract data from a file using AI.

Parameters:

file_id (str): ID of the file
fields (str): Fields to extract

Returns: Extracted data in JSON format

`box_list_folder_content_by_folder_id`

List folder contents.

Parameters:

folder_id (str): ID of the folder
is_recursive (bool): Whether to list recursively

Returns: Folder content in JSON format with id, name, type, and description

`box_manage_folder_tool`

Create, update, or delete folders in Box.

Parameters:

action (str): Action to perform: "create", "delete", or "update"
folder_id (str, optional): ID of the folder (required for delete/update)
name (str, optional): Folder name (required for create, optional for update)
parent_id (str, optional): Parent folder ID (required for create, optional for update)
description (str, optional): Folder description (optional for update)
recursive (bool, optional): Whether to delete recursively (optional for delete)

Returns: Status message with folder details

`box_upload_file_tool`

Upload content as a file to Box.

Parameters:

content (str): The content to upload as a file
file_name (str): The name to give the file in Box
folder_id (Any, optional): The ID of the folder to upload to

Returns: Upload status with file ID and name

`box_download_file_tool`

Download a file from Box and return its content.

Parameters:

file_id (Any): The ID of the file to download
save_file (bool, optional): Whether to save the file locally
save_path (str, optional): Path where to save the file

Returns: File content as text, base64-encoded image, or save status message

Requirements

Python 3.13 or higher
Box API credentials (Client ID, Client Secret, etc.)

Installation

Clone the repository:

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

Install uv if not installed yet:

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"

Create and set up our project:

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

Create a .env file in the root directory and add your Box API credentials:
```
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
```

Usage

Running the MCP Server

To start the MCP server, run the following command:

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

Using Claude as the client

Edit your claude_desktop_config.json

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

And add the following:

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

[!NOTE] If using MacOS, you will want to install uv with brew: brew install uv or provide the full path to the uv executable: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

If Claude is running restart it

Using Cursor as the client

Open your IDE with Cursor
In settings, select Cursor settings.
In the left nav, select MCP.
In the top-left, select Add new global MCP server.
Past the following json, being sure to update for your local values:

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

Save and close the mcp.json file, and ensure the MCP server is enabled. You may have to restart.

Running Tests

The project includes a suite of tests to verify Box API functionality. Before running the tests, you'll need to update the file and folder IDs in the test files to match files in your Box account.

Setting Up Tests

Update File and Folder IDs:
- Each test file (in the tests/ directory) contains hardcoded IDs for Box files and folders
- You need to replace these IDs with IDs of files and folders in your Box account
- Example: In test_box_api_read.py, replace "1728677291168" with the ID of a file in your Box account
Test File ID References:
- test_box_api_read.py: Needs a valid document file ID (e.g., a Word document)
- test_box_api_search.py: Update the search queries and file extensions to match your content
- test_box_api_ai.py: Needs a file ID for testing AI extraction capabilities
- Other test files may require specific folder IDs or file types

Running Tests

Once you've updated the file IDs, you can run tests using 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

Available Tests

test_box_auth.py: Tests authentication functionality
test_box_api_basic.py: Basic Box API tests
test_box_api_read.py: Tests file reading capabilities
test_box_api_search.py: Tests search functionality
test_box_api_ai.py: Tests AI-based features
test_box_api_file_ops.py: Tests file upload and download operations

Creating New Tests

When creating new tests:

Follow the pattern in existing test files
Use the box_client fixture for authenticated API access
Clean up any test files or folders created during tests
Add proper assertions to verify functionality

Troubleshooting

If you are on MacOS and running the MCP server with Claude Desktop and you see the following error:

Error: spawn uv ENOENT

you can either remove uv and re-install with brew: brew install uv or provide the full path to the uv executable: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py