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:

Install uv if not installed yet: 2.1 MacOS+Linux 2.2 Windows

Create and set up our project: 3.1 MacOS+Linux 3.1 Windows

Create a .env file in the root directory and add your Box API credentials:

Usage

Running the MCP Server

To start the MCP server, run the following command:

Using Claude as the client

Edit your claude_desktop_config.json

And add the following:

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

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:

Test File ID References:

Running Tests

Once you've updated the file IDs, you can run tests using pytest:

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

MCP Server Box

Description

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:

Install uv if not installed yet: 2.1 MacOS+Linux 2.2 Windows

Create and set up our project: 3.1 MacOS+Linux 3.1 Windows

Create a .env file in the root directory and add your Box API credentials:

Usage

Running the MCP Server

To start the MCP server, run the following command:

Using Claude as the client

Edit your claude_desktop_config.json

And add the following:

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

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:

Test File ID References:

Running Tests

Once you've updated the file IDs, you can run tests using pytest:

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

Box

MCP Server Box

Description

Tools implemented

Box Tools

`box_who_am_i`

`box_authorize_app_tool`

`box_search_tool`

`box_read_tool`

`box_ask_ai_tool`

`box_search_folder_by_name`

`box_ai_extract_data`

`box_list_folder_content_by_folder_id`

`box_manage_folder_tool`

`box_upload_file_tool`

`box_download_file_tool`

Requirements

Installation

Usage

Running the MCP Server

Using Claude as the client

Using Cursor as the client

Running Tests

Setting Up Tests

Running Tests

Available Tests

Creating New Tests

Troubleshooting

MCP Server Box

Description

Tools implemented

Box Tools

`box_who_am_i`

`box_authorize_app_tool`

`box_search_tool`

`box_read_tool`

`box_ask_ai_tool`

`box_search_folder_by_name`

`box_ai_extract_data`

`box_list_folder_content_by_folder_id`

`box_manage_folder_tool`

`box_upload_file_tool`

`box_download_file_tool`

Requirements

Installation

Usage

Running the MCP Server

Using Claude as the client

Using Cursor as the client

Running Tests

Setting Up Tests

Running Tests

Available Tests

Creating New Tests

Troubleshooting

Related servers

MagicSlides MCP Server

Time

CUA MCP Server

WhatsApp Bridge