Box MCP Server

Description

The Box MCP Server 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.

Tools Implemented# Box API Tools

box_who_am_i

Get your current user information and check connection status.

• Returns: User information dictionary

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): The query to search for.
• file_extensions (List[str], optional): File extensions to filter results.
• where_to_look_for_query (List[str], optional): Locations to search (e.g. NAME, DESCRIPTION, FILE_CONTENT, COMMENTS, TAG).
• ancestor_folder_ids (List[str], optional): List of folder IDs in which to search.
• Returns: The search results as a newline-separated list of file names and IDs.

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

The MCP server supports four transport methods: stdio (default), SSE (Server-Sent Events), HTTP (StreamableHttp), and FastAPI.

Running with stdio transport (default)

uv --directory /path/to/mcp-server-box run src/mcp_server_box.py

Running Tests

The project includes comprehensive test suites for both unit tests and integration tests to verify Box API functionality.

Troubleshooting

If you receive the error Error: spawn uv ENOENT on MacOS when running the MCP server with Claude Desktop, you may:

• Remove uv and reinstall it with Homebrew: brew install uv
• Or provide the full path to the uv executable in your configuration:

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