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

Quick Start

Clone the repository:

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

Optional but recommended uv installation for virtual environment and dependency management:

Homebrew (macOS)

brew install uv

WinGet (Windows)

winget install --id=astral-sh.uv  -e

On macOS and Linux

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

On Windows

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

Set up the virtual environment and install dependencies:

uv sync

Set environment variables:

Set the following environment variables for Box authentication in a .env file or your system environment.

For comprehensive authentication configuration options, see the Authentication Guide.

Using OAuth2.0 with a Box App

BOX_CLIENT_ID = YOUR_CLIENT_ID
BOX_CLIENT_SECRET = YOUR_CLIENT_SECRET
BOX_REDIRECT_URL = http://localhost:8000/callback

# MCP Server Authentication (for HTTP transports)
BOX_MCP_SERVER_AUTH_TOKEN = YOUR_BOX_MCP_SERVER_AUTH_TOKEN
OAUTH_PROTECTED_RESOURCES_CONFIG_FILE = .oauth-protected-resource.json

Note:

• The BOX_MCP_SERVER_AUTH_TOKEN is used to authenticate the MCP client to the MCP server when using --mcp-auth-type=token (independent of Box authentication)

Run the MCP server in STDIO mode:

uv run src/mcp_server_box.py

Box Community MCP Server Tools

Below is a summary of the available tools:

Tools available	Description
box_tools_ai	AI-powered file and hub queries
box_tools_collaboration	Manage file/folder collaborations
box_tools_docgen	Document generation and template management
box_tools_files	File operations (read, upload, download)
box_tools_folders	Folder operations (list, create, delete, update)
box_tools_generic	Generic Box API utilities
box_tools_groups	Group management and queries
box_tools_metadata	Metadata template and instance management
box_tools_search	Search files and folders
box_tools_shared_links	Shared link management for files/folders/web-links
box_tools_tasks	Task and task assignment management
box_tools_users	User management and queries
box_tools_web_link	Web link creation and management

Box Community MCP Server Operations Details

Command line interface parameters

To run the MCP server with specific configurations, you can use the following command line parameters:

uv run src/mcp_server_box.py --help

usage: mcp_server_box.py [-h] [--transport {stdio,sse,http}] [--host HOST] [--port PORT] [--mcp-auth-type {oauth,token,none}] [--box-auth-type {oauth,ccg,jwt,mcp_client}]

Box Community MCP Server

options:
  -h, --help            show this help message and exit
  --transport {stdio,sse,http}
                        Transport type (default: stdio)
  --host HOST           Host for SSE/HTTP transport (default: localhost)
  --port PORT           Port for SSE/HTTP transport (default: 8005)
  --mcp-auth-type {oauth,token,none}
                        Authentication type for MCP server (default: token)
  --box-auth-type {oauth,ccg,jwt,mcp_client}
                        Authentication type for Box API (default: oauth)

For detailed information about authentication types, configurations, and use cases, see the Authentication Guide.

Claude Desktop Configuration

STDIO mode

Edit your claude_desktop_config.json:

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

Add the configuration:

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

Restart Claude if it is running.

HTTP Mode

Assuming your MCP server is running on https://mcp.myserver.com/mcp

1. Go to Claude -> Settings -> Connectors
2. Select Add custom connector
3. Configurations:
   1. Give it a name
   2. Enter the URL e.g. https://mcp.myserver.com/mcp
   3. Optionally enter the client id and client secret
4. Click add
5. Click connect. The OAuth flow should start. Complete the flow
6. Back in Claude, click Configure. You should see all the tools available.