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.

Installation

Prerequisites

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:

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

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

Create and set up our project:

  # Create virtual environment and activate it
  uv venv
  source .venv/bin/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.

Running Box MCP server locally

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.

Use Cursor as the Box MCP client

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.

Use Claude as the Box MCP client

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 desktop app.
Authenticate the Box MCP server using box_authorize_app_tool tool.

Available tools

Authentication and Authorization

Tool	Description	Parameters	Returns
`get_box_client`	Helper function to get Box client from context	`ctx (Context)`: Request context.	Box client instance
`box_who_am_i`	Get the current user’s information	`ctx (Context)`: Request context.	User information string
`box_authorize_app_tool`	Authorize the Box application	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

File Operations

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
`get_file_content`	Extract text content from a file	`file_id (str)`: File ID.	Text file content

Folder Management

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

Box AI

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

Collaborations

Tool	Description	Parameters	Returns
`box_collaboration_list_by_file_tool`	List all collaborations on a specific file	`ctx (Context)`: Request context. `file_id (str)`: ID of the Box file.	List of collaborations in JSON format
`box_collaboration_list_by_folder_tool`	List all collaborations on a specific folder	`ctx (Context)`: Request context. `folder_id (str)`: ID of the Box folder.	List of collaborations in JSON format
`box_collaboration_delete_tool`	Delete a specific collaboration	`ctx (Context)`: Request context. `collaboration_id (str)`: ID of the collaboration.	Deletion confirmation
`box_collaboration_file_group_by_group_id_tool`	Add a group as a collaborator to a file	`ctx (Context)`: Request context. `file_id (str)`: ID of the Box file. `group_id (str)`: ID of the group. `role (str, optional)`: Collaboration role (default: “editor”).	Created collaboration details

Groups

Tool	Description	Parameters	Returns
`box_groups_search_tool`	Search for groups by name (partial match)	`ctx (Context)`: Request context. `query (str)`: Search query.	List of matching groups in JSON format
`box_groups_list_members_tool`	List all members of a specific group	`ctx (Context)`: Request context. `group_id (str)`: ID of the group.	List of group members in JSON format
`box_groups_list_by_user_tool`	List all groups that a specific user belongs to	`ctx (Context)`: Request context. `user_id (str)`: ID of the user.	List of groups in JSON format

Users

Tool	Description	Parameters	Returns
`box_users_list_tool`	List all users in the Box account	`ctx (Context)`: Request context.	List of users in JSON format
`box_users_locate_by_name_tool`	Locate a user by their name (exact match)	`ctx (Context)`: Request context. `name (str)`: Name of the user.	User details in JSON format
`box_users_locate_by_email_tool`	Locate a user by their email address (exact match)	`ctx (Context)`: Request context. `email (str)`: Email address.	User details in JSON format
`box_users_search_by_name_or_email_tool`	Search for users by name or email (partial match)	`ctx (Context)`: Request context. `query (str)`: Search query.	List of matching users in JSON format

Box Shared Links

Tool	Description	Parameters	Returns
`box_shared_link_file_get_tool`	Get a shared link for a file	`ctx (Context)`: Request context. `file_id (str)`: ID of the file.	Shared link details in JSON format
`box_shared_link_file_create_or_update_tool`	Create or update a shared link for a file	`ctx (Context)`: Request context. `file_id (str)`: ID of the file. `access (str, optional)`: Access level. `can_download (bool, optional)`: Can download. `can_preview (bool, optional)`: Can preview. `can_edit (bool, optional)`: Can edit. `password (str, optional)`: Password. `vanity_name (str, optional)`: Vanity name. `unshared_at (str, optional)`: Expiration date.	Created/updated shared link details in JSON format

Box Tools Web Link

Tool	Description	Parameters	Returns
`box_web_link_create_tool`	Create a Box web link	`ctx (Context)`: Request context. `url (str)`: URL of the web link. `parent_folder_id (str)`: Parent folder ID. `name (str, optional)`: Name of the web link. `description (str, optional)`: Description.	Created web link details in JSON format
`box_web_link_get_by_id_tool`	Get a Box web link by its ID	`ctx (Context)`: Request context. `web_link_id (str)`: ID of the web link.	Web link details in JSON format
`box_web_link_update_by_id_tool`	Update a Box web link by its ID	`ctx (Context)`: Request context. `web_link_id (str)`: ID of the web link. `url (str)`: New URL.	Updated web link details in JSON format

Box Doc Gen

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

Box Metadata

Tool	Description	Parameters	Returns
`box_metadata_template_get_by_key_tool`	Retrieves a metadata template by its key.	`template_name (str)`: The key of the metadata template to retrieve.	The metadata template associated with the provided key.
`box_metadata_template_get_by_name_tool`	Retrieve a metadata template by its name.	`template_name (str)`: The name of the metadata template to retrieve.	The metadata template associated with the provided name.
`box_metadata_template_create_tool`	Create a metadata template.	`ctx (Context)`: The context object `display_name (str)`: The display name of the metadata template `fields (List[Dict[str, Any]])`: A list of field definitions with type, key, displayName, description, hidden, and options (for enum/multiSelect) `template_key (Optional[str])`: An optional key for the metadata template	The created metadata template.
`box_metadata_set_instance_on_file_tool`	Set a metadata instance on a file.	`ctx (Context)`: The context object `template_key (str)`: The key of the metadata template `file_id (str)`: The ID of the file to set metadata on `metadata (dict)`: The metadata values to set	The metadata instance associated with the file.
`box_metadata_update_instance_on_file_tool`	Update a metadata instance on a file.	`ctx (Context)`: The context object `file_id (str)`: The ID of the file to update metadata on `template_key (str)`: The key of the metadata template `metadata (dict)`: The metadata values to update `remove_non_included_data (bool)`: If True, removes fields not included in metadata	The response from the Box API after updating the metadata.
`box_metadata_delete_instance_on_file_tool`	Delete a metadata instance on a file.	`ctx (Context)`: The context object `file_id (str)`: The ID of the file to delete metadata from `template_key (str)`: The key of the metadata template	The response from the Box API after deleting the metadata.

Troubleshooting

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.

​Installation

​Prerequisites

​Running Box MCP server locally

​Use Cursor as the Box MCP client

​Use Claude as the Box MCP client

​Available tools

​Authentication and Authorization

​Search and Navigation

​File Operations

​Folder Management

​Box AI

​Collaborations

​Groups

​Users

​Box Shared Links

​Box Tools Web Link

​Box Doc Gen

​Box Metadata

​Troubleshooting