MCP Server Box

🚀 MCP Server Box

MCP Server Box is a Python-based project designed to integrate with the Box API. It offers a variety of features, including file search, text extraction, AI-driven capabilities, and file upload and download operations.

🚀 Quick Start

MCP Server Box is a Python - based project integrating with the Box API. It provides functions like file search, text extraction, etc.

✨ Features

Core Components

• Box API Integration: Utilizes the box-sdk-gen library to interact with the Box cloud storage service.
• MCP Framework: Based on the Model Context Protocol, it manages and coordinates communication between different modules.
• Functional Features:
  • File search
  • Text extraction
  • AI - driven features
  • File upload and download

📦 Installation

System Requirements

• Operating System: Supports MacOS/Linux or Windows.
• Memory: At least 2GB RAM is recommended.
• Others: Python and pip need to be installed.

Installation Steps

1. Clone the repository

   git clone https://github.com/your-repository-url/mcp-server-box.git
   cd mcp-server-box
   

2. Install the uv tool

   # Install uv globally
   pip install uv
   
   # Create and activate a virtual environment (MacOS/Linux)
   uv venv
   source .venv/bin/activate
   
   # Create and activate a virtual environment (Windows)
   uv venv
   ./.venv/Scripts/activate
   

3. Lock dependencies

   # Lock project dependencies
   uv lock
   
   # Install dependencies to the virtualenv
   pip install -r requirements.txt
   

4. Configure environment variables Create a .env file and add the following content:

   BOX_CLIENT_ID=Your client ID
   BOX_CLIENT_SECRET=Your client secret
   

💻 Usage Examples

Start the MCP Server

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

Configure the Claude Client (Optional)

1. Open the Claude configuration file:

   code ~/Library/Application\ 支持/Claude/claude_desktop_config.json
   

2. Add the following content to the mcpServers node:

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

3. Restart the Claude application.

Test Suite

Prepare the Test Environment

1. Update file and folder IDs:

   • In each test file under the tests/ directory, replace all hard - coded Box file and folder IDs.
   • Example: In test_box_api_read.py, replace "1728677291168" with a valid file ID in your Box account.

2. Test case descriptions:

   • test_box_auth.py: Verify the authentication function.
   • test_box_api_basic.py: Test basic Box API functions.
   • test_box_api_read.py: Test file reading capabilities.
   • test_box_api_search.py: Test the search function.
   • test_box_api_ai.py: Test AI - driven functions.
   • test_box_api_file_ops.py: Test file upload and download operations.

Execute Tests

# Run all tests
pytest

# Run a specific test file
pytest tests/test_box_api_file_ops.py

# Run tests in verbose mode
pytest -v

# Show print output and run tests
pytest -v -s

🔧 Troubleshooting

Common Issues

• Dependencies not installed: Ensure that all project dependencies are correctly installed.
• Incorrect environment variable configuration: Check if BOX_CLIENT_ID and BOX_CLIENT_SECRET in the .env file are correct.
• Permission issues: Ensure that your Box account has sufficient permissions to access test files.

Solutions

1. Reinstall project dependencies:

   pip install -r requirements.txt
   

2. Verify environment variables:

   echo $BOX_CLIENT_ID
   echo $BOX_CLIENT_SECRET
   

3. Check Box account permissions and update IDs in test files.

Other Resources

• Box Developer Documentation
• uv Tool Documentation
• Python Official Documentation