Overview

The Box MCP Server provides a bridge between Box APIs and clients that speak the Model Context Protocol (MCP). By configuring Box authentication via environment variables (in a .env file or system environment), developers can run a local or hosted MCP server that exposes Box operations to AI assistants, automation tools, and other MCP clients.

This guide explains which Box-related environment variables the MCP server expects, how to set them safely, and how to run the server in common modes (stdio, SSE/HTTP). It is intended for developers new to the repository who need a concise, practical reference for getting authentication up and running.

Features

Simple environment-variable configuration for Box authentication (OAuth2, CCG, JWT, or MCP client)
Runs in multiple transports: stdio (local), sse, http
Works with MCP authentication types: token, oauth, none
Ships with a broad set of Box tools (files, folders, users, groups, search, AI tools, etc.)
Supports local .env files for development and system environment variables for production

Installation / Configuration

Prerequisites: Python environment and the uv tool (recommended for managing virtual environments and dependencies).

Install uv (optional but recommended):

macOS (Homebrew)

brew install uv

Windows (WinGet)

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

macOS / Linux (curl)

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

Windows (PowerShell)

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

Clone and install dependencies:

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

Set Box authentication environment variables. You can put these in a .env file at the project root (recommended for local development) or export them into your system environment for production.

Example .env (OAuth2 app + MCP server token):

# OAuth2 (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 MCP clients (HTTP transports)
BOX_MCP_SERVER_AUTH_TOKEN=YOUR_BOX_MCP_SERVER_AUTH_TOKEN

# Optional: path to resources config for OAuth-protected resources
OAUTH_PROTECTED_RESOURCES_CONFIG_FILE=.oauth-protected-resource.json

Key variables and notes:

BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_REDIRECT_URL — Required for OAuth2 user flows.
BOX_MCP_SERVER_AUTH_TOKEN — Token used to authenticate an MCP client to the MCP server when running with –mcp-auth-type=token. This is distinct from Box API credentials.
OAUTH_PROTECTED_RESOURCES_CONFIG_FILE — Optional file path for defining resource-specific OAuth protections.
Other Box auth modes supported: set –box-auth-type to one of {oauth, ccg, jwt, mcp_client} and provide the appropriate credentials (e.g., JWT key file or CCG service account).

Security best practice: never commit .env files or secrets to source control. Add .env to .gitignore and prefer secret managers or environment variables in CI/CD and production.

Run the MCP server (stdio mode):

uv run src/mcp_server_box.py

Run with CLI options:

uv run src/mcp_server_box.py --transport http --host 0.0.0.0 --port 8005 --mcp-auth-type token --box-auth-type oauth

Show help:

uv run src/mcp_server_box.py -- --help

Available Tools / Resources

The server bundles a collection of Box-focused MCP tools. Key modules include:

Tool	Purpose
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 templates and instances
box_tools_search	Search files and folders
box_tools_shared_links	Shared link management
box_tools_tasks	Task and assignment management
box_tools_users	User management and queries
box_tools_web_link	Web link creation and management

Documentation and configuration references:

docs/authentication.md — detailed authentication types and examples
docs/*.md — per-tool documentation (see repo docs folder)

Use Cases

Local development with an AI assistant (STDIO)
- Run the MCP server in stdio mode while developing tools or debugging integrations.
- Use a .env file with OAuth client ID/secret for signing in via local callback.
- Command:
```
uv run src/mcp_server_box.py
```
Hosting an HTTP MCP endpoint for a client (e.g., Claude Desktop)
- Start the server with –transport http and set BOX_MCP_SERVER_AUTH_TOKEN.
- Configure the client to point to https://your-host/mcp and use the token or OAuth flow depending on mcp-auth-type.
- Example:
```
uv run src/mcp_server_box.py --transport http --host mcp.myserver.com --port 443 --mcp-auth-type token
```
Machine-to-machine automation (CCG / JWT)
- Use Client Credentials Grant (CCG) or JWT auth for unattended server-to-Box interactions.
- Set the appropriate environment variables or key file references and run in a secure environment (server/CI).
Hybrid: MCP server authenticates to Box with a service account while MCP clients authenticate with tokens for access control.

Notes and Troubleshooting

BOX_MCP_SERVER_AUTH_TOKEN is separate from Box API credentials; it secures MCP client <-> MCP server communication.
If you change auth method (–box-auth-type or –mcp-auth-type), update environment variables accordingly and restart the server.
Consult docs/authentication.md for detailed examples of OAuth, CCG, JWT, and mcp_client configurations.

For full source and additional documentation, see the repository: https://github.com/box-community/mcp-server-box.

Box Authentication Environment Variables for MCP Server