Box Mcp Server

What is Box Mcp Server about?

Box Mcp Server provides a collection of tools that expose Box API capabilities through the Model Context Protocol (MCP). It enables programmatic file search, content extraction, AI‑driven questioning, metadata manipulation, and document generation, all from a unified Python server.

How to use Box Mcp Server?

1. Clone the repository

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

2. Install UV (Python package manager)
   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
3. Create a virtual environment and lock dependencies

   uv venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   uv lock
   

4. Add Box credentials in a .env file (OAuth or CCG format as described in the README).
5. Run the server (default stdio transport):

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

6. Configure your client (Claude, Cursor, etc.) to point to the command above as an MCP server.

Key features of Box Mcp Server

• User authentication (box_who_am_i, box_authorize_app_tool).
• File search with filters for extensions, locations, and ancestor folders.
• Content reading for any Box file (box_read_tool).
• AI querying on single or multiple files, hubs, and free‑form prompts.
• Structured data extraction using field definitions or templates, with enhanced options.
• Folder management (create, update, delete, recursive listing).
• File upload/download from local paths or raw content (including base64 handling).
• Metadata templates creation, retrieval, and instance CRUD operations on files.
• DocGen workflow: create templates, generate documents from JSON payloads, list and manage jobs.
• Multiple transport methods: stdio, SSE, HTTP, FastAPI.

Use cases of Box Mcp Server

• Enterprise knowledge bases: Search across documents, extract key data, and surface answers via AI.
• Automated onboarding: Upload policy documents, tag them with metadata, and generate personalized PDFs.
• Compliance reporting: Pull files, extract structured fields, and compile audit reports automatically.
• Content migration: List folder trees recursively, download, transform, and re‑upload with updated metadata.
• Custom AI assistants: Integrate with Claude or Cursor to provide on‑the‑fly insights from a Box drive.

FAQ from the Box Mcp Server

Q: Which Python version is required? A: Python 3.13 or higher.

Q: Do I need a Box developer account? A: Yes. You must obtain a client ID and secret (OAuth) or set up CCG credentials.

Q: Can I run the server as a web service? A: Yes. Use the --transport http or --transport fastapi options (details in the source code).

Q: How do I handle large files when downloading? A: Use box_download_file_tool with save_file=true and provide a save_path to write directly to disk.

Q: Is there support for pagination in search results? A: The underlying Box SDK provides pagination; the tool returns a newline‑separated list, and you can adjust parameters in the request.

Q: What if I need to set environment variables for credentials? A: Place them in a .env file at the project root; the server reads them automatically.

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. The Box MCP Server project aims to provide a robust and flexible solution for managing and processing Box data using advanced AI and machine learning techniques.

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.

box_read_tool

Read the text content of a Box file.

Parameters:

• file_id (str): ID of the file to read

Returns: File content

box_ask_ai_tool

Ask Box AI about a file.

Parameters:

• file_id (str): ID of the file
• prompt (str): Question for the AI

Returns: AI response

box_hubs_ask_ai_tool

Ask Box AI about a hub. There is currently no way via API to discover a hub ID, so you must know the ID to use this tool. We will fix this in the future.

Parameters:

• hubs_id (str): ID of the hub
• prompt (str): Question for the AI

Returns: AI response

box_search_folder_by_name

Locate a folder by name.

Parameters:

• folder_name (str): Name of the folder

Returns: Folder ID

box_ai_extract_data

Extract data from a file using AI.

Parameters:

• file_id (str): ID of the file
• fields (str): Fields to extract

Returns: Extracted data in JSON format

box_list_folder_content_by_folder_id

List folder contents.

Parameters:

• folder_id (str): ID of the folder
• is_recursive (bool): Whether to list recursively

Returns: Folder content in JSON format with id, name, type, and description

box_manage_folder_tool

Create, update, or delete folders in Box.

Parameters:

• action (str): Action to perform: "create", "delete", or "update"
• folder_id (str, optional): ID of the folder (required for delete/update)
• name (str, optional): Folder name (required for create, optional for update)
• parent_id (str, optional): Parent folder ID (required for create, optional for update)
• description (str, optional): Folder description (optional for update)
• recursive (bool, optional): Whether to delete recursively (optional for delete)

Returns: Status message with folder details

box_search_folder_by_name_tool

Locate a folder in Box by its name.

• Parameters:
  • folder_name (str): Name of the folder.
• Returns: Information (name and ID) about matching folders.

Box AI Tools

box_ai_ask_file_single_tool

Query Box AI regarding a single file.

• Parameters:
  • file_id (str): The file identifier.
  • prompt (str): Query or instruction for the AI.
  • ai_agent_id (str, optional): The ID of the AI agent to use.
• Returns: AI response based on the file content.

box_ai_ask_file_multi_tool

Query Box AI using multiple files.

• Parameters:
  • file_ids (List[str]): List of file IDs.
  • prompt (str): Instruction for the AI based on the aggregate content.
  • ai_agent_id (str, optional): The ID of the AI agent to use.
• Returns: AI-generated answer considering all files provided.

box_ai_ask_hub_tool

Ask Box AI about a hub.

• Parameters:
  • hubs_id (str): ID of the hub.
  • prompt (str): Question for the AI.
  • ai_agent_id (str, optional): The ID of the AI agent to use.
• Returns: AI response based on the hub content.

box_ai_extract_freeform_tool

Extract data from files using AI with a freeform prompt.

• Parameters:
  • file_ids (List[str]): The IDs of the files to read.
  • prompt (str): The freeform prompt to guide the AI extraction.
  • ai_agent_id (str, optional): The ID of the AI agent to use.
• Returns: Extracted data in JSON format.

box_ai_extract_structured_using_fields_tool

Extract structured data from files using AI with specified fields.

• Parameters:
  • file_ids (List[str]): The IDs of the files to read.
  • fields (List[dict]): The fields to extract from the files.
  • ai_agent_id (str, optional): The ID of the AI agent to use.
• Returns: Extracted structured data in JSON format.

box_ai_extract_structured_using_template_tool

Extract structured data from files using AI with a specified template.

• Parameters:
  • file_ids (List[str]): The IDs of the files to read.
  • template_key (str): The ID of the template to use for extraction.
  • ai_agent_id (str, optional): The ID of the AI agent to use.
• Returns: Extracted structured data in JSON format.

box_ai_extract_structured_enhanced_using_fields_tool

Extract structured data from files using AI with enhanced processing and specified fields.

• Parameters:
  • file_ids (List[str]): The IDs of the files to read.
  • fields (List[dict]): The fields to extract from the files.
• Returns: Enhanced extracted structured data in JSON format.

box_ai_extract_structured_enhanced_using_template_tool

Extract structured data from files using AI with enhanced processing and a template.

• Parameters:
  • file_ids (List[str]): The IDs of the files to read.
  • template_key (str): The ID of the template to use for extraction.
• Returns: Enhanced extracted structured data in JSON format.

Box File Tools

box_read_tool

Read the text content of a Box file.

• Parameters:
  • file_id (str): The ID of the file to be read.
• Returns: Text content of the file.

box_list_folder_content_by_folder_id

List a folder's content using its ID.

• Parameters:
  • folder_id (str): Folder ID.
  • is_recursive (bool, optional): Whether to list the content recursively.
• Returns: Folder contents as a JSON string including id, name, type, and description.

box_manage_folder_tool

Create, update, or delete a folder in Box.

• Parameters:
  • action (str): Action to perform: "create", "delete", or "update".
  • folder_id (str, optional): Folder ID (required for delete and update).
  • name (str, optional): Folder name (required for create, optional for update).
  • parent_id (str, optional): Parent folder ID (defaults to "0" for root).
  • description (str, optional): Description for the folder (for update).
  • recursive (bool, optional): For recursive delete.
• Returns: Status message with folder details.

box_upload_file_from_path_tool

Upload a file to Box from a local filesystem path.

• Parameters:
  • file_path (str): Local file path.
  • folder_id (str, optional): Destination folder ID (defaults to "0").
  • new_file_name (str, optional): New file name (if not provided, uses the original file name).
• Returns: Details about the uploaded file (ID and name) or an error message.

box_upload_file_from_content_tool

Upload content as a file to Box.

• Parameters:
  • content (str | bytes): Content to upload (text or binary).
  • file_name (str): The name to assign the file.
  • folder_id (str, optional): Destination folder ID (defaults to "0").
  • is_base64 (bool, optional): Indicates if the provided content is base64 encoded.
• Returns: Upload success message with file ID and name.

box_download_file_tool

Download a file from Box.

• Parameters:
  • file_id (str): The ID of the file to download.
  • save_file (bool, optional): Whether to save the file locally.
  • save_path (str, optional): The local path where the file should be saved.
• Returns: For text files, returns the content; for images, returns base64‑encoded data; for other types, an error or save‑confirmation message.

Box Metadata Tools

box_metadata_template_create_tool

Create a metadata template.

• Parameters:
  • display_name (str): The display name of the metadata template.
  • fields (List[Dict]): A list of fields to include in the template.
  • template_key (str, optional): An optional key for the metadata template.
• Returns: The created metadata template.

box_metadata_template_get_by_key_tool

Retrieve a metadata template by its key.

• Parameters:
  • template_name (str): The key of the metadata template to retrieve.
• Returns: The metadata template associated with the provided key.

box_metadata_template_get_by_name_tool

Retrieve a metadata template by its name.

• Parameters:
  • template_name (str): The name of the metadata template to retrieve.
• Returns: The metadata template associated with the provided name.

box_metadata_set_instance_on_file_tool

Set a metadata instance on a file.

• Parameters:
  • template_key (str): The key of the metadata template.
  • file_id (str): The ID of the file to set the metadata on.
  • metadata (dict): The metadata to set.
• Returns: The response from the Box API after setting the metadata.

box_metadata_get_instance_on_file_tool

Get a metadata instance on a file.

• Parameters:
  • file_id (str): The ID of the file to get the metadata from.
  • template_key (str): The key of the metadata template.
• Returns: The metadata instance associated with the file.

box_metadata_update_instance_on_file_tool

Update a metadata instance on a file.

• Parameters:
  • file_id (str): The ID of the file to update the metadata on.
  • template_key (str): The key of the metadata template.
  • metadata (dict): The metadata to update.
  • remove_non_included_data (bool, optional): If True, remove data from fields not included in the metadata.
• Returns: The response from the Box API after updating the metadata.

box_metadata_delete_instance_on_file_tool

Delete a metadata instance on a file.

• Parameters:
  • file_id (str): The ID of the file to delete the metadata from.
  • template_key (str): The key of the metadata template.
• Returns: The response from the Box API after deleting the metadata.

Box Doc Gen Tools

box_docgen_create_batch_tool

Generate documents using a Box Doc Gen template and a local JSON file.

• Parameters:
  • file_id (str): Template file ID.
  • destination_folder_id (str): Folder ID where generated documents should be stored.
  • user_input_file_path (str): Path to a JSON file with input data.
  • output_type (str, optional): Output format (default is "pdf").
• Returns: The result of the document generation batch as a JSON string.

box_docgen_get_job_tool

Fetch a single Doc Gen job by its ID.

• Parameters:
  • job_id (str): The job identifier.
• Returns: Job details in a JSON‑formatted string.

box_docgen_list_jobs_tool

List all Doc Gen jobs associated with the current user.

• Parameters:
  • marker (str | None, optional): Pagination marker.
  • limit (int | None, optional): Maximum number of jobs to return.
• Returns: Paginated list of jobs in pretty‑printed JSON.

box_docgen_list_jobs_by_batch_tool

List Doc Gen jobs belonging to a specific batch.

• Parameters:
  • batch_id (str): The batch identifier.
  • marker (str | None, optional): Pagination marker.
  • limit (int | None, optional): Maximum number of jobs to return.
• Returns: Batch jobs details as JSON.

box_docgen_template_create_tool

Mark a file as a Box Doc Gen template.

• Parameters:
  • file_id (str): File ID to mark as a template.
• Returns: Template details after marking.

box_docgen_template_list_tool

List all available Box Doc Gen templates.

• Parameters:
  • marker (str | None, optional): Pagination marker.
  • limit (int | None, optional): Maximum number of templates to list.
• Returns: List of templates in JSON format.

box_docgen_template_delete_tool

Remove the Doc Gen template marking from a file.

• Parameters:
  • template_id (str): The template identifier.
• Returns: Confirmation of deletion as JSON.

box_docgen_template_get_by_id_tool

Retrieve details of a specific Doc Gen template.

• Parameters:
  • template_id (str): The template identifier.
• Returns: Template details as JSON.

box_docgen_template_list_tags_tool

List all tags associated with a Box Doc Gen template.

• Parameters:
  • template_id (str): The template ID.
  • template_version_id (str | None, optional): Specific version ID.
  • marker (str | None, optional): Pagination marker.
  • limit (int | None, optional): Maximum number of tags to return.
• Returns: List of tags in JSON format.

box_docgen_template_list_jobs_tool

List all Doc Gen jobs that used a specific template.

• Parameters:
  • template_id (str): The template identifier.
  • marker (str | None, optional): Pagination marker.
  • limit (int | None, optional): Maximum number of jobs to list.
• Returns: Job details for the template as a JSON string.

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:

For OAuth .env BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret BOX_REDIRECT_URL = http://localhost:8000/callback

For CCG .env BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret BOX_SUBJECT_TYPE = user # or enterprise BOX_SUBJECT_ID = your user id or enterprise id

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

Using Claude as the client

For stdio transport (recommended for Claude Desktop)

1. Edit your claude_desktop_config.json:

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

2. Add the configuration:

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

3. Restart Claude if it is running.

Using Cursor as the client

For stdio transport

1. Open your IDE with Cursor.

2. In settings, select Cursor settings.

3. In the left nav, select MCP.

4. In the top-left, click Add new global MCP server.

5. Paste the following JSON (update for your local values):

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

6. Save and close the mcp.json file, and restart if necessary.

[!NOTE] Make sure your Box API credentials in .env are correctly set.