home / mcp / box mcp server

Box MCP Server

Securely connect AI agents to your enterprise content in Box

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "box-community-mcp-server-box": {
      "command": "uv",
      "args": [
        "run",
        "src/mcp_server_box.py"
      ],
      "env": {
        "BOX_CLIENT_ID": "YOUR_CLIENT_ID",
        "BOX_REDIRECT_URL": "http://localhost:8000/callback",
        "BOX_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "BOX_MCP_SERVER_AUTH_TOKEN": "YOUR_BOX_MCP_SERVER_AUTH_TOKEN",
        "OAUTH_PROTECTED_RESOURCES_CONFIG_FILE": ".oauth-protected-resource.json"
      }
    }
  }
}

You run a Box MCP Server to enable programmatic access to Box-associated capabilities through a standardized MCP interface. This server lets you host Box-related MCP endpoints locally or remotely, so clients can perform authenticated actions and access tools securely through the MCP protocol.

How to use

You connect to the Box MCP Server from an MCP client to perform actions like file operations, metadata handling, and collaboration management through a consistent MCP API. Start the local server, then point your MCP client at the server’s URL or standard input/output stream. Use the provided tools to perform tasks such as reading, uploading, or organizing Box content, managing users and groups, and automating document workflows.

How to install

Follow these concrete steps to set up the Box MCP Server on your machine. Ensure you have a supported runtime and a network connection.

# Step 1: Clone the Box MCP Server repository
git clone https://github.com/box-community/mcp-server-box.git
cd mcp-server-box

# Step 2: Install the virtual environment manager (recommended)
# macOS/Linux: uv is installed via installer script
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows: install uv via WinGet
winget install --id=astral-sh.uv  -e

# Optional: macOS/Windows users may also install uv with their preferred method
# macOS Homebrew example shown for reference
# brew install uv

# Step 3: Synchronize dependencies into the virtual environment
uv sync

# Step 4: Set environment variables for Box MCP authentication
# Use a .env file or export variables in your shell
# Example values shown as placeholders
export BOX_CLIENT_ID=YOUR_CLIENT_ID
export BOX_CLIENT_SECRET=YOUR_CLIENT_SECRET
export BOX_REDIRECT_URL=http://localhost:8000/callback
export BOX_MCP_SERVER_AUTH_TOKEN=YOUR_BOX_MCP_SERVER_AUTH_TOKEN
export OAUTH_PROTECTED_RESOURCES_CONFIG_FILE=.oauth-protected-resource.json

# Step 5: Run the MCP server in STDIO mode
uv run src/mcp_server_box.py

Additional configuration and notes

The server supports OAuth2.0 with a Box App and uses an MCP server authentication token for HTTP transports. You can run in STDIO mode (local process I/O) or, depending on future setups, you may use HTTP transports. You can inspect runtime options and defaults by querying the server help.

uv run src/mcp_server_box.py --help

Security and environment variables

Keep your Box credentials and MCP tokens secure. Do not commit secrets into code repositories. Store sensitive values in a secure environment or use a dedicated secret manager.

Environment variables shown for Box authentication and MCP configuration include:

Claude Desktop and client integration (optional)

If you use Claude Desktop, you can configure a local STDIO MCP server and a HTTP mode connector to access Box MCP Server tools from Claude.

# STDIO mode configuration example for Claude Desktop
# Edit claude_desktop_config.json with the following mapping
{
  "mcpServers": {
    "box_mcp": {
      "command": "uv",
      "args": ["run", "src/mcp_server_box.py"]
    }
  }
}

CLI usage for server parameters

You can customize the MCP server behavior using command line options. The available options include transport type, host, port, authentication type for the MCP server, and authentication type for the Box API.

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}]

Available tools

box_tools_ai

AI-powered queries for files and hubs in Box

box_tools_collaboration

Manage file and folder collaborations

box_tools_docgen

Document generation and template management

box_tools_files

File operations such as read, upload, and download

box_tools_folders

Folder operations including list, create, delete, and update

box_tools_generic

Generic Box API utilities for common tasks

box_tools_groups

Group management and queries across Box resources

box_tools_metadata

Metadata templates and instance management

box_tools_search

Search across Box files and folders

box_tools_shared_links

Manage shared links for files, folders, and web links

box_tools_tasks

Task creation, assignment, and tracking

box_tools_users

User management and queries in Box

box_tools_web_link

Web link creation and management