Box MCP Server

Description

The Box MCP Server 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 Box MCP Server 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 API 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): The query to search for.
- file_extensions (List[str], optional): File extensions to filter results.
- where_to_look_for_query (List[str], optional): Locations to search (e.g. NAME, DESCRIPTION, FILE_CONTENT, COMMENTS, TAG).
- ancestor_folder_ids (List[str], optional): List of folder IDs in which to search.
Returns: The search results as a newline‑separated list of file names and IDs.

`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_hubs_ask_ai_tool`

Ask Box AI about a hub. There is currently no way via API to discover a hub ID, so you must know the ID to use this tool. We will fix this in the future.

Parameters:

hubs_id (str): ID of the hub
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`

=======

Parameters:
- file_id (str): The ID of the file to be read.
Returns: Text content of the file.

`box_ask_ai_tool`

Query Box AI regarding a single file.

Parameters:
- file_id (str): The file identifier.
- prompt (str): Query or instruction for the AI.
Returns: AI response based on the file content.

`box_ask_ai_tool_multi_file`

Query Box AI using multiple files.

Parameters:
- file_ids (List[str]): List of file IDs.
- prompt (str): Instruction for the AI based on the aggregate content.
Returns: AI-generated answer considering all files provided.

`box_search_folder_by_name`

Locate a folder in Box by its name.

Parameters:
- folder_name (str): Name of the folder.
Returns: Information (name and ID) about matching folders.

`box_ai_extract_data`

Extract specific fields from a file using AI.

Parameters:
- file_id (str): ID of the file.
- fields (str): Comma‑separated list of fields to extract.
Returns: Extracted data in JSON string format.

`box_list_folder_content_by_folder_id`

List a folder’s content using its ID.

Parameters:
- folder_id (str): Folder ID.
- is_recursive (bool, optional): Whether to list the content recursively.
Returns: Folder contents as a JSON string including id, name, type, and description.

`box_manage_folder_tool`

Create, update, or delete a folder in Box.

Parameters:
- action (str): Action to perform: "create", "delete", or "update".
- folder_id (str, optional): Folder ID (required for delete and update).
- name (str, optional): Folder name (required for create, optional for update).
- parent_id (str, optional): Parent folder ID (defaults to "0" for root).
- description (str, optional): Description for the folder (for update).
- recursive (bool, optional): For recursive delete.
Returns: Status message with folder details.

`box_upload_file_from_path_tool`

Upload a file to Box from a local filesystem path.

Parameters:
- file_path (str): Local file path.
- folder_id (str, optional): Destination folder ID (defaults to "0").
- new_file_name (str, optional): New file name (if not provided, uses the original file name).
Returns: Details about the uploaded file (ID and name) or an error message.

`box_upload_file_from_content_tool`

Upload content as a file to Box.

Parameters:
- content (str | bytes): Content to upload (text or binary).
- file_name (str): The name to assign the file.
- folder_id (str, optional): Destination folder ID (defaults to "0").
- is_base64 (bool, optional): Indicates if the provided content is base64 encoded.
Returns: Upload success message with file ID and name.

`box_download_file_tool`

Download a file from Box.

Parameters:
- file_id (str): The ID of the file to download.
- save_file (bool, optional): Whether to save the file locally.
- save_path (str, optional): The local path where the file should be saved.
Returns: For text files, returns the content; for images, returns base64‑encoded data; for other types, an error or save‑confirmation message.

Box Doc Gen Tools

`box_docgen_create_batch_tool`

Generate documents using a Box Doc Gen template and a local JSON file.

Parameters:
- file_id (str): Template file ID.
- destination_folder_id (str): Folder ID where generated documents should be stored.
- user_input_file_path (str): Path to a JSON file with input data.
- output_type (str, optional): Output format (default is "pdf").
Returns: The result of the document generation batch as a JSON string.

`box_docgen_get_job_tool`

Fetch a single Doc Gen job by its ID.

Parameters:
- job_id (str): The job identifier.
Returns: Job details in a JSON‑formatted string.

`box_docgen_list_jobs_tool`

List all Doc Gen jobs associated with the current user.

Parameters:
- marker (str | None, optional): Pagination marker.
- limit (int | None, optional): Maximum number of jobs to return.
Returns: Paginated list of jobs in pretty‑printed JSON.

`box_docgen_list_jobs_by_batch_tool`

List Doc Gen jobs belonging to a specific batch.

Parameters:
- batch_id (str): The batch identifier.
- marker (str | None, optional): Pagination marker.
- limit (int | None, optional): Maximum number of jobs to return.
Returns: Batch jobs details as JSON.

`box_docgen_template_create_tool`

Mark a file as a Box Doc Gen template.

Parameters:
- file_id (str): File ID to mark as a template.
Returns: Template details after marking.

`box_docgen_template_list_tool`

List all available Box Doc Gen templates.

Parameters:
- marker (str | None, optional): Pagination marker.
- limit (int | None, optional): Maximum number of templates to list.
Returns: List of templates in JSON format.

`box_docgen_template_delete_tool`

Remove the Doc Gen template marking from a file.

Parameters:
- template_id (str): The template identifier.
Returns: Confirmation of deletion as JSON.

`box_docgen_template_get_by_id_tool`

Retrieve details of a specific Doc Gen template.

Parameters:
- template_id (str): The template identifier.
Returns: Template details as JSON.

`box_docgen_template_list_tags_tool`

List all tags associated with a Box Doc Gen template.

Parameters:
- template_id (str): The template ID.
- template_version_id (str | None, optional): Specific version ID.
- marker (str | None, optional): Pagination marker.
- limit (int | None, optional): Maximum number of tags to return.
Returns: List of tags in JSON format.

`box_docgen_template_list_jobs_tool`

List all Doc Gen jobs that used a specific template.

Parameters:
- template_id (str): The template identifier.
- marker (str | None, optional): Pagination marker.
- limit (int | None, optional): Maximum number of jobs to list.
Returns: Job details for the template as a JSON string.

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.2 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

Add the configuration:

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

Restart Claude if it is running.

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, click Add new global MCP server.

Paste the following JSON (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 restart if necessary.

Running Tests

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

Setting Up Tests

Update File and Folder IDs:
- Each test file (in the tests/ directory) uses hardcoded IDs for Box files and folders.
- Replace these IDs with valid IDs from your Box account.
File ID References:
- For example, in tests/test_box_api_read.py, replace "1728677291168" with a valid file ID.

Running Tests

Once you've updated the IDs, you can run the 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 Test Suites

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.
Additional tests cover folder operations and Doc Gen features.

Troubleshooting

If you receive the error Error: spawn uv ENOENT on MacOS when running the MCP server with Claude Desktop, you may:

Remove uv and reinstall it with Homebrew: brew install uv

Or provide the full path to the uv executable in your configuration:

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

[!NOTE] Make sure your Box API credentials in .env are correctly set.

Box

Box MCP Server

Description

Tools Implemented

Box API Tools

box_who_am_i

box_authorize_app_tool

box_search_tool

box_read_tool

box_ask_ai_tool

box_hubs_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_ask_ai_tool

box_ask_ai_tool_multi_file

box_search_folder_by_name

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 Doc Gen Tools

box_docgen_create_batch_tool

box_docgen_get_job_tool

box_docgen_list_jobs_tool

box_docgen_list_jobs_by_batch_tool

box_docgen_template_create_tool

box_docgen_template_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

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 Test Suites

Troubleshooting

Related Servers

Google Drive

Tencent Cloud COS MCP

Box

`box_who_am_i`

`box_authorize_app_tool`

`box_search_tool`

`box_read_tool`

`box_ask_ai_tool`

`box_hubs_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_ask_ai_tool`

`box_ask_ai_tool_multi_file`

`box_search_folder_by_name`

`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_template_create_tool`

`box_docgen_template_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`