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:

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

BOX_MCP_SERVER_AUTH_TOKEN = YOUR_BOX_MCP_SERVER_AUTH_TOKEN

Using CCG with a Box App

BOX_CLIENT_ID = YOUR_CLIENT_ID
BOX_CLIENT_SECRET = YOUR_CLIENT_SECRET
BOX_SUBJECT_TYPE = user_or_enterprise
BOX_SUBJECT_ID = YOUR_USER_OR_ENTERPRISE_ID

BOX_MCP_SERVER_AUTH_TOKEN = YOUR_BOX_MCP_SERVER_AUTH_TOKEN

Note: The BOX_MCP_SERVER_AUTH_TOKEN is the token used to authenticate requests to the Box MCP server. You can generate this token.

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,streamable-http}] [--host HOST]
                         [--port PORT] [--box-auth {oauth,ccg}] [--no-mcp-server-auth]

Box Community MCP Server

options:
  -h, --help            show this help message and exit
  --transport {stdio,sse,streamable-http}
                        Transport type (default: stdio)
  --host HOST           Host for SSE/HTTP transport (default: 0.0.0.0)
  --port PORT           Port for SSE/HTTP transport (default: 8000)
  --box-auth {oauth,ccg}
                        Authentication type for Box API (default: oauth)
  --no-mcp-server-auth  Disable authentication (for development only)

Claude Desktop Configuration

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.

Cursor Configuration

Cursor supports MCP servers through its configuration file. Here's how to set it up:

The Cursor MCP configuration file is located at:

• macOS/Linux: ~/.cursor/config.json or ~/.config/cursor/config.json
• Windows: %APPDATA%\Cursor\config.json

Add the MCP Server Configuration: STDIO Transport

Edit your Cursor configuration file and add the following under the mcpServers section:

{
    "mcpServers": {
        "mcp-server-box": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/mcp-server-box",
                "run",
                "src/mcp_server_box.py"
            ],
            "env": {
                "BOX_CLIENT_ID": "YOUR_CLIENT_ID",
                "BOX_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
                "BOX_REDIRECT_URL": "http://localhost:8000/callback"
            }
        }
    }
}