MCP Server Box

Description

box-sdk-gen

Tools implemented

Box Tools

box_who_am_i

box_authorize_app_tool

box_search_tool

• 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

box_read_tool

• file_id

  (str): ID of the file to read

box_ask_ai_tool

• file_id

  (str): ID of the file

• prompt

  (str): Question for the AI

box_search_folder_by_name

• folder_name

  (str): Name of the folder

box_ai_extract_data

• file_id

  (str): ID of the file

• fields

  (str): Fields to extract

box_list_folder_content_by_folder_id

• folder_id

  (str): ID of the folder

• is_recursive

  (bool): Whether to list recursively

box_manage_folder_tool

• 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)

box_upload_file_tool

• 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

box_download_file_tool

• 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

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

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

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

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

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

Running Tests

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

# 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

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

Error: spawn uv ENOENT

brew install uv

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