An MCP server capable of interacting with the Box API
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.
box_who_am_iGet your current user information and check connection status.
Returns: User information string
box_authorize_app_toolStart the Box application authorization process.
Returns: Authorization status message
box_search_toolSearch for files in Box.
Parameters:
query (str): Search queryfile_extensions (List[str], optional): File extensions to filter bywhere_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 withinReturns: Search results
box_read_toolRead the text content of a Box file.
Parameters:
file_id (str): ID of the file to readReturns: File content
box_ask_ai_toolAsk Box AI about a file.
Parameters:
file_id (str): ID of the fileprompt (str): Question for the AIReturns: AI response
box_search_folder_by_nameLocate a folder by name.
Parameters:
folder_name (str): Name of the folderReturns: Folder ID
box_ai_extract_dataExtract data from a file using AI.
Parameters:
file_id (str): ID of the filefields (str): Fields to extractReturns: Extracted data in JSON format
box_list_folder_content_by_folder_idList folder contents.
Parameters:
folder_id (str): ID of the folderis_recursive (bool): Whether to list recursivelyReturns: Folder content in JSON format with id, name, type, and description
box_manage_folder_toolCreate, 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_toolUpload content as a file to Box.
Parameters:
content (str): The content to upload as a filefile_name (str): The name to give the file in Boxfolder_id (Any, optional): The ID of the folder to upload toReturns: Upload status with file ID and name
box_download_file_toolDownload a file from Box and return its content.
Parameters:
file_id (Any): The ID of the file to downloadsave_file (bool, optional): Whether to save the file locallysave_path (str, optional): Path where to save the fileReturns: File content as text, base64-encoded image, or save status message
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
To start the MCP server, run the following command:
uv --directory /Users/anovotny/Desktop/mcp-server-box run src/mcp_server_box.py
claude_desktop_config.jsoncode ~/Library/Application\ Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"mcp-server-box": {
"command": "uv",
"args": [
"--directory",
"/Users/anovotny/Desktop/mcp-server-box",
"run",
"src/mcp_server_box.py"
]
}
}
}
## 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:
```bash
# 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
test_box_auth.py: Tests authentication functionalitytest_box_api_basic.py: Basic Box API teststest_box_api_read.py: Tests file reading capabilitiestest_box_api_search.py: Tests search functionalitytest_box_api_ai.py: Tests AI-based featurestest_box_api_file_ops.py: Tests file upload and download operationsWhen creating new tests:
box_client fixture for authenticated API access