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

1. Clone the repository:

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

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

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

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

1. Edit your claude_desktop_config.json

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

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

3. If Claude is running restart it

Using Cursor as the client

1. Open your IDE with Cursor

2. In settings, select Cursor settings.

3. In the left nav, select MCP.

4. In the top-left, select Add new global MCP server.

5. 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"
      ]
    }
  }
}

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

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

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

1. Follow the pattern in existing test files
2. Use the box_client fixture for authenticated API access
3. Clean up any test files or folders created during tests
4. 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