Box Integration

Integrate Claude Code with the Box cloud content management platform for file search, text extraction, AI-powered document analysis, and folder management through MCP.

When to Use This MCP Server

Connect this server when you need to:

• Search and retrieve files from Box storage directly within Claude Code for document review, content extraction, or reference during development
• Extract text content from documents, spreadsheets, and presentations stored in Box for analysis or data processing workflows
• Leverage Box AI capabilities for document querying, summarization, and intelligent data extraction from enterprise content

Consider alternatives when:

• Your files are stored in local filesystems, Google Drive, or Dropbox, which have their own storage access methods or MCP servers
• You only need simple file uploads or downloads without Box's AI-powered analysis features, where the Box CLI may be simpler

Quick Start

Configuration

Copy
name: box-integration
type: mcp
category: devtools

Example Connection

Copy
claude mcp:connect box-integration

Available Tools

search-files:       Search Box for files by name, content, metadata, or custom attributes
extract-text:       Extract plain text content from documents, PDFs, and spreadsheets
ai-query:           Ask questions about document content using Box AI capabilities
list-folders:       Browse folder hierarchies and retrieve folder contents with metadata
download-file:      Download file content for local processing and analysis

Core Concepts

Box MCP Server Overview

Aspect	Details
Transport	stdio-based Python process using box-sdk-gen for API communication
Authentication	Box JWT application credentials or OAuth 2.0 with developer token
AI Features	Box AI for document Q&A, summarization, and structured data extraction
Search	Full-text search across all indexed Box content with metadata filtering
File Support	PDFs, Office documents, images with OCR, and 120+ file types

Box MCP Architecture

Claude Code IDE
    |
    v
[MCP Client] --stdio--> [mcp-server-box (Python)]
                              |
                              v
                     [box-sdk-gen Library]
                              |
                    +---------+---------+
                    |         |         |
                    v         v         v
              [Content   [Search    [Box AI
               API]       API]      API]
                    \         |         /
                     [Box Cloud Platform]
                       Enterprise Content

Configuration

Parameter	Type	Default	Description
BOX_CLIENT_ID	string	required	Box application client ID from the Box Developer Console
BOX_CLIENT_SECRET	string	required	Box application client secret for OAuth authentication
BOX_DEVELOPER_TOKEN	string	optional	Short-lived developer token for quick testing (expires in 60 min)
box_server_path	string	required	Local filesystem path to the mcp-server-box Python project directory
default_folder_id	string	0	Default Box folder ID to scope operations; 0 represents the root folder

Best Practices

1. Use JWT Authentication for Production - Developer tokens expire after 60 minutes and are unsuitable for sustained work. Configure JWT-based authentication with a Box service account for persistent, uninterrupted access to Box content during long development sessions.

2. Scope Search with Folder IDs - When searching for files, specify ancestor_folder_ids to limit search scope to relevant directories. Unscoped searches across an entire enterprise Box account return too many irrelevant results and are slower.

3. Leverage AI Query for Document Understanding - Instead of extracting full text and parsing it manually, use the ai-query tool to ask specific questions about document content. Box AI handles context windowing and relevance ranking automatically.

4. Cache Extracted Text Locally - When working with the same documents repeatedly, save extracted text to local files. This reduces API calls and avoids re-processing large documents that have not changed since the last extraction.

5. Use Metadata Filters for Precision - Box supports custom metadata templates on files and folders. Use metadata-based search filters to find documents by project, department, or status without relying on filename conventions alone.

Common Issues

1. Developer Token Expired During Session - Developer tokens last only 60 minutes. If operations start failing mid-session, generate a new token from the Box Developer Console or switch to JWT authentication for longer-lived access.

2. File Content Extraction Returns Empty - Some file types require Box to generate a text representation before extraction. Recently uploaded files may need a few minutes for indexing. Retry extraction after waiting for background processing to complete.

3. Permission Denied on Enterprise Content - The Box application's service account must be granted access to the specific folders you are trying to access. Contact your Box administrator to add the service account as a collaborator on the relevant folder.