mcp -box

This Box MCP Server provides a programmable gateway to Box data through a collection of dedicated tools. The server exposes an HTTP/STDIO transport and supports OAuth or token-based authentication for Box API access. Once running, you can access a suite of tools (such as box_tools_ai, box_tools_files, box_tools_folders, box_tools_metadata, and more) to perform tasks like AI-assisted queries, file and folder operations, metadata management, document generation, and user/group administration. The server is designed to be used with clients like Claude Desktop or your own integrations; you can start it with uv run src/mcp_server_box.py and then connect to the configured transport and authentication mode. Each tool is documented under docs/, for example docs/box_tools_files.md, describing usage patterns and available endpoints. Ensure you configure BOX_CLIENT_ID, BOX_CLIENT_SECRET, and authentication tokens to enable secure access to Box resources.

Prerequisites:

• Python installed (via uv as a Python environment manager is recommended).
• uv installed (a modern Python environment/CLI) as described in the repository.
• Git to clone the repository.

Step-by-step installation:

1. Install uv (or ensure it is available):
   • macOS: brew install uv
   • Windows: winget install --id=astral-sh.uv -e
   • macOS/Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
2. Clone the MCP server repository: git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box
3. Synchronize dependencies and environment (example using uv): uv sync
4. Configure environment variables for Box authentication. Create a file named .env or set variables in your environment with: 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 OAUTH_PROTECTED_RESOURCES_CONFIG_FILE=.oauth-protected-resource.json
5. Start the MCP server: uv run src/mcp_server_box.py

Note: If you choose to run in a different transport or environment, adjust the command accordingly but keep the same Python entry point (src/mcp_server_box.py).

Tips and common issues:

• Ensure Box application credentials (CLIENT_ID and CLIENT_SECRET) are valid and that the Redirect URL matches your OAuth configuration.
• If you encounter token authentication errors, verify BOX_MCP_SERVER_AUTH_TOKEN and the OAuth scopes configured for your Box app.
• The server supports multiple CLI parameters (uv run src/mcp_server_box.py --help) to customize transport, host, port, and authentication type; use this to tailor the server to your environment.
• Store sensitive credentials securely (avoid committing .env files to version control).
• The list of tools is extensive; consult docs/ for individual tool usage and capabilities (e.g., box_tools_files.md for file operations or box_tools_metadata.md for template management).