📦 Model Context Protocol (MCP) Server Box: Unleashing AI on Your Box Data

Overview

The MCP Server Box project is a powerful Python-based solution that seamlessly bridges the gap between Large Language Model (LLM) applications and the wealth of data stored within your Box account. By leveraging the Model Context Protocol (MCP), this project provides a standardized and efficient way to connect LLMs with Box, enabling you to build intelligent applications that can search, extract, analyze, and manage your Box content with unprecedented ease. Whether you're developing an AI-powered IDE, enhancing a chat interface with document understanding, or creating custom AI-driven workflows, MCP Server Box empowers you to unlock the full potential of your Box data.

Core Capabilities: A Toolkit for AI-Powered Box Interactions

MCP Server Box provides a comprehensive suite of tools designed to facilitate a wide range of interactions with the Box API. These tools are built upon the box-sdk-gen library and are carefully crafted to provide a robust and flexible foundation for your AI-powered applications.

Box Fundamentals

box_who_am_i: Establishes your connection and retrieves your user information, ensuring you're properly authenticated and ready to interact with your Box account.
- Returns: A string containing your user information.
box_authorize_app_tool: Initiates the Box application authorization process, guiding you through the necessary steps to grant your application access to your Box data.
- Returns: An authorization status message.

Content Discovery

box_search_tool: Locates files within your Box account based on a variety of criteria, allowing you to quickly find the information you need.
- Parameters:
  - query (str): The search term to use.
  - file_extensions (List[str], optional): A list of file extensions to filter the search (e.g., ["pdf", "docx"]).
  - where_to_look_for_query (List[str], optional): Specifies where to search for the query (e.g., ["NAME", "FILE_CONTENT"]).
  - ancestor_folder_ids (List[str], optional): A list of folder IDs to restrict the search to specific folders.
- Returns: Search results matching your criteria.
box_search_folder_by_name: Quickly identifies a folder by its name, providing you with its unique ID for further operations.
- Parameters:
  - folder_name (str): The name of the folder to search for.
- Returns: The folder ID if found.
box_list_folder_content_by_folder_id: Retrieves a detailed listing of the contents within a specified folder, providing essential information about each item.
- Parameters:
  - folder_id (str): The ID of the folder to list.
  - is_recursive (bool): A flag to indicate whether to list contents recursively (including subfolders).
- Returns: Folder content in JSON format, including id, name, type, and description for each item.

Content Extraction and Analysis

box_read_tool: Extracts the textual content from a Box file, making it readily available for analysis and processing.
- Parameters:
  - file_id (str): The ID of the file to read.
- Returns: The file content as a string.
box_ask_ai_tool: Leverages the power of AI to answer questions about a specific file, providing insightful summaries and answers based on the file's content.
- Parameters:
  - file_id (str): The ID of the file to query.
  - prompt (str): The question you want to ask the AI.
- Returns: The AI's response to your question.
box_ai_extract_data: Intelligently extracts specific data fields from a file using AI, enabling you to automate data capture and processing.
- Parameters:
  - file_id (str): The ID of the file to extract data from.
  - fields (str): A comma-separated list of the fields you want to extract (e.g., "name, address, phone_number").
- Returns: The extracted data in JSON format.

Content Management

box_manage_folder_tool: Provides a unified interface for creating, updating, and deleting folders within your Box account, streamlining your content organization.
- Parameters:
  - action (str): The action to perform: "create", "delete", or "update".
  - folder_id (str, optional): The ID of the folder to modify (required for "delete"/"update").
  - name (str, optional): The new folder name (required for "create", optional for "update").
  - parent_id (str, optional): The ID of the parent folder (required for "create", optional for "update").
  - description (str, optional): The folder description (optional for "update").
  - recursive (bool, optional): Whether to delete recursively (optional for "delete").
- Returns: A status message with folder details.
box_upload_file_tool: Uploads content to Box as a new file, allowing you to easily add data to your Box environment.
- Parameters:
  - content (str): The content to upload as a file.
  - file_name (str): The desired name for the file in Box.
  - folder_id (Any, optional): The ID of the folder to upload the file to.
- Returns: Upload status with the file ID and name.
box_download_file_tool: Downloads a file from Box, providing you with its content for local processing or analysis.
- 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): The path to save the file to (if save_file is True).
- Returns: The file content as text, a base64-encoded image, or a save status message.

Getting Started: Installation and Configuration

Follow these steps to set up and configure the MCP Server Box project:

Clone the Repository:

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

Install uv (if not already installed):

MacOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Create and Set Up Your Project:

MacOS/Linux:

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Lock the dependencies
uv lock

Windows:

# Create virtual environment and activate it
uv venv
.venv\Scripts\activate

# Lock the dependencies
uv lock

Configure Box API Credentials:

Create a .env file in the root directory of the project and add your Box API credentials:
```
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
```

Running the MCP Server

To start the MCP server, execute the following command:

uv --directory /Users/anovotny/Desktop/mcp-server-box run src/mcp_server_box.py

Note: Replace /Users/anovotny/Desktop/mcp-server-box with the actual path to your project directory.

Integrating with Claude (Example Client)

This section demonstrates how to integrate MCP Server Box with Claude, a popular AI assistant.

Edit claude_desktop_config.json:

Open the configuration file for Claude:

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

Add MCP Server Configuration:

Add the following configuration block to the claude_desktop_config.json file:

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

Note: Again, replace /Users/anovotny/Desktop/mcp-server-box with the correct path to your project directory.

Restart Claude:

If Claude is currently running, restart it to apply the new configuration.

Testing and Validation

The MCP Server Box project includes a comprehensive suite of tests to ensure the reliability and correctness of its functionality.

Setting Up Tests

Before running the tests, you must update the file and folder IDs in the test files to match the actual files and folders in your Box account. This is crucial for the tests to execute correctly.

Locate Test Files:

The test files are located in the tests/ directory.
Update File and Folder IDs:
- Open each test file and carefully examine the hardcoded file and folder IDs.
- Replace these IDs with the corresponding IDs from your Box account.
- Example: In test_box_api_read.py, replace "1728677291168" with the ID of a valid document file in your Box account.
Specific Test File Requirements:
- test_box_api_read.py: Requires the ID of a valid document file (e.g., a Word document, PDF).
- test_box_api_search.py: Requires updating the search queries and file extensions to match the content in your Box account.
- test_box_api_ai.py: Requires the ID of a file suitable for testing AI extraction capabilities.
- Other test files may have specific requirements for folder IDs or file types.

Running Tests

Once you have updated the file and folder 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 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 these guidelines:

Follow Existing Patterns: Adhere to the structure and conventions used in the existing test files.
Use the box_client Fixture: Utilize the box_client fixture to obtain an authenticated API client for interacting with Box.
Clean Up Test Data: Ensure that any test files or folders created during the tests are properly cleaned up to avoid polluting your Box environment.
Add Assertions: Include appropriate assertions to verify that the functionality being tested is working as expected.

Troubleshooting

[Add troubleshooting tips and common issues here]

Box