Self-hosted Box MCP Server

Guides Box MCP Server Self-hosted Box MCP Server

Self-hosted Box MCP Server

The Self-hosted 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 Python Next Gen SDK library and provides a set of tools to interact with Box files and folders.

Python 3.13 or higher
Box Platform app credentials (Client ID, Client Secret)

Follow the steps from this section to set up the self-hosted Box MCP Server.

Clone the repository:

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

Install uv if it's not installed on your machine:

MacOS/Linux

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

Windows

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

Restart your terminal afterwards to ensure that the uv command gets picked up.

Create and set up our 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

Create a .env file in the root directory and fill your Box Platform app credentials:

BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret

You can also watch a video tutorial and see example usage of Box MCP tools.

To start the Box MCP Server, run the following command:

uv --directory /Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box run src/mcp_server_box.py

Update the path so it reflects your local setup.

Prerequisites:

Download Cursor desktop app

Follow these instructions to start using Box MCP Sever with Cursor:

Open the Cursor app.
Click the cog icon to open settings.
Select MCP within the Cursor Settings tab.
Click the Add new global MCP server button. This opens the mcp.json file.
Update the values with your local setup and paste the following JSON:

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

Save and close the mcp.json file.
Restart Cursor if necessary.
Use the box_authorize_app_tool tool to start using Box MCP.

Prerequisites:

Download Claude for Desktop client
Optionally, set up code command for VS Code

Follow these steps to set up Box MCP in Claude for Desktop:

Edit your claude_desktop_config.json.

You can run this command in your terminal:

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

Alternatively, in the main Claude navigation choose Settings. Select the Developers tab and click Edit Config. This opens a folder window containing claude_desktop_config.json.

Add the configuration:

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

Restart Claude for Desktop.
Authenticate the Box MCP Server using box_authorize_app_tool tool.

Tool	Description	Parameters	Returns
`box_who_am_i`	Gets the current user information and checks the connection status.	None	User information string.
`box_authorize_app_tool`	Starts the Box application authorization process.	None	Authorization status message.

Tool	Description	Parameters	Returns
`box_search_tool`	Search for files in Box	`query (str):` Search query. `file_extensions (List[str], optional):` Filter by extensions. `where_to_look_for_query (List[str], optional):` Locations to search. `ancestor_folder_ids (List[str], optional):` Folder IDs to limit the search.	Newline-separated list of file names and IDs
`box_search_folder_by_name`	Locate a folder by name	`folder_name (str):` Name of the folder	Folder ID and information
`box_list_folder_content_by_folder_id`	List folder contents	`folder_id (str):` ID of the folder. `is_recursive (bool):` Whether to list recursively.	Folder content in JSON format

Tool	Description	Parameters	Returns
`box_read_tool`	Read the text content of a Box file	`file_id (str):` ID of the file to read.	File content
`box_upload_file_from_path_tool`	Upload a file from local path	`file_path (str):` Local file path. `folder_id (str, optional):` Destination folder ID. `new_file_name (str, optional):` New file name.	File details or error message
`box_upload_file_from_content_tool`	Upload content as a file	`content (str\|bytes):` Content to upload. `file_name (str):` File name. `folder_id (str, optional):` Destination folder ID. `is_base64 (bool, optional):` If content is base64 encoded.	Upload success message
`box_download_file_tool`	Download a file from Box	`file_id (str):` File ID. `save_file (bool, optional):` Whether to save locally. `save_path (str, optional):` Local save path.	File content or save confirmation

Tool	Description	Parameters	Returns
`box_manage_folder_tool`	Create, update, or delete folders	`action (str):` `create`, `delete`, or `update`. `folder_id (str, optional):` Folder ID. `name (str, optional):` Folder name. `parent_id (str, optional):` Parent folder ID. `description (str, optional):` Folder description. `recursive (bool, optional):` For recursive delete.	Status message with folder details

Tool	Description	Parameters	Returns
`box_ask_ai_tool`	Ask Box AI about a file	`file_id (str):` File ID. `prompt (str):` Question for the AI.	AI response
`box_ask_ai_tool_multi_file`	Query Box AI using multiple files	`file_ids (List[str]):` List of file IDs. `prompt (str):` Instruction for AI.	AI-generated answer
`box_hubs_ask_ai_tool`	Ask Box AI about a hub	`hubs_id (str):` ID of the hub. `prompt (str):` Question for the AI.	AI response
`box_ai_extract_data`	Extract data from a file using AI	`file_id (str):` File ID. `fields (str):` Fields to extract.	Extracted data in JSON format

Tool	Description	Parameters	Returns
`box_docgen_create_batch_tool`	Generate documents using a template	`file_id` (str): Template file ID. `destination_folder_id` (str): Output folder ID. `user_input_file_path` (str): JSON input data path. `output_type` (str, optional): Output format.	Batch generation result
`box_docgen_get_job_tool`	Fetch a Doc Gen job by ID	`job_id (str):` Job identifier	Job details in JSON
`box_docgen_list_jobs_tool`	List all Doc Gen jobs	`marker (str, optional):` Pagination marker. `limit (int, optional):` Max jobs to return.	List of jobs in JSON
`box_docgen_list_jobs_by_batch_tool`	List jobs in a specific batch	`batch_id (str):` Batch identifier. `marker (str, optional):` Pagination marker. `limit (int, optional):` Max jobs to return.	Batch jobs details
`box_docgen_template_create_tool`	Mark a file as a template	`file_id (str):` File ID to mark	Template details
`box_docgen_template_list_tool`	List all available templates	`marker` (str, optional): Pagination marker. `limit` (int, optional): Max templates to list.	List of templates
`box_docgen_template_delete_tool`	Remove template marking	`template_id (str):` Template identifier	Deletion confirmation
`box_docgen_template_get_by_id_tool`	Get template details	`template_id (str):` Template identifier	Template details
`box_docgen_template_list_tags_tool`	List template tags	`template_id` (str): Template ID. `template_version_id` (str, optional): Version ID. `marker` (str, optional): Pagination marker. `limit` (int, optional): Max tags to return.	List of tags
`box_docgen_template_list_jobs_tool`	List jobs using a template	`template_id (str):` Template identifier. `marker (str, optional):` Pagination marker. `limit (int, optional):` Max jobs to list.	Job details

In case of an Error: spawn uv ENOENT on MacOS when running the MCP server with Claude Desktop, you can:

Remove uv and reinstall it with Homebrew: brew install uv.
Provide the full path to the uv executable in your configuration:

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

In case of additional issues related to setup, post your question on our Developer Community forum.

Self-hosted Box MCP Server

Self-hosted Box MCP Server

Installation

Prerequisites

Running Box MCP Server locally

Use Cursor as the Box MCP client

Use Claude for Desktop as the Box MCP client

Available tools

Authentication and user tools

Search and navigation tools

File operations

Folder Management

Box AI tools

Box Doc Gen tools

Troubleshooting