dennisonbertram/mcp-box

Box MCP Server

A Model Context Protocol (MCP) server that provides secure access to Box cloud storage without local file persistence. This server enables Large Language Models to interact with Box files, folders, and AI capabilities through a standardized MCP interface.

Features

🔧 8 Core Tools (Intent-Based)

• box_save_documents - Batch upload documents with automatic folder creation
• box_read_document - Stream document content without local storage
• box_manage_folders - Create and organize folder structures
• box_explore_storage - Navigate Box directory tree with filtering
• box_share_content - Create shared links and manage collaborations
• box_analyze_document - Use Box AI for document analysis, Q&A, and extraction
• box_search_content - Natural language search with advanced filtering
• box_retrieve_documents - Batch retrieval with optional local saving

📚 MCP Resources (6 URI Templates)

• box://file/{fileId} - Access specific Box files by ID
• box://folder/{folderId} - Access specific Box folders by ID
• box://search?q={query} - Search Box content with query parameters
• box://user/storage - Current user's storage quota and usage
• box://user/recent - Recently accessed files
• box://folder/root/tree - Complete folder structure from root

💬 MCP Prompts (5 Interactive Templates)

• share_file - Create shared links with customizable permissions
• analyze_document - Use Box AI to analyze documents with specific prompts
• organize_folder - Organize files using different strategies (by date, type, name)
• bulk_upload - Upload multiple files with folder organization
• collaboration_setup - Set up collaboration with specific users and roles

🔒 Security & Compliance

• Zero Local Storage - All documents remain in Box cloud
• Multi-Auth Support - OAuth 2.0, Client Credentials Grant (CCG), JWT
• Encrypted Credentials - Secure token storage and auto-refresh
• Enterprise-Grade - Leverages Box's enterprise security features

Quick Start

Prerequisites

1. Box Developer Account - Create at Box Developer Console
2. Node.js 18+ - Download Node.js
3. Box App Configuration - OAuth 2.0 or Client Credentials Grant app

Installation

# Clone and install
git clone https://github.com/your-org/mcp-box
cd mcp-box
npm install

# Build the server
npm run build

Configuration

Create a .env file in the project root:

# Authentication Method (oauth | ccg)
AUTH_TYPE=oauth

# Box App Credentials
BOX_CLIENT_ID=your_client_id_here
BOX_CLIENT_SECRET=your_client_secret_here
BOX_ENTERPRISE_ID=your_enterprise_id_here  # Required for CCG

# Server Configuration
MCP_TRANSPORT=stdio              # stdio | http
LOG_LEVEL=info                   # debug | info | warn | error
NODE_ENV=development

Authentication Setup

OAuth 2.0 (Recommended for individual use)

Step 1: Box Developer Console Setup

1. Go to Box Developer Console: https://developer.box.com/

2. Create Custom App:

   • Click "Create New App"
   • Select "Custom App"
   • Choose "User Authentication (OAuth 2.0)"
   • Name your app (e.g., "MCP Box Server")

3. Configure OAuth Settings:

   • Redirect URI: http://localhost:3000/auth/callback
   • Application Scopes: Select all needed permissions:
     • ✅ Read all files and folders
     • ✅ Write all files and folders
     • ✅ Manage users
     • ✅ Manage enterprise properties
   • Save your configuration

4. Get Credentials:

   • Copy Client ID
   • Copy Client Secret

Step 2: Configure Your .env File

# OAuth 2.0 Configuration
AUTH_TYPE=oauth
BOX_CLIENT_ID=your_client_id_here
BOX_CLIENT_SECRET=your_client_secret_here

# Server Configuration
MCP_TRANSPORT=stdio
LOG_LEVEL=info
NODE_ENV=development

Step 3: First-Time Authentication

# Build and start the server
npm run build
npm start

What happens:

1. Server detects no stored OAuth tokens
2. Opens browser to Box login page automatically
3. You log in with your Box credentials
4. Box redirects back with authorization code
5. Server exchanges code for access/refresh tokens
6. Tokens are securely stored for future use

Client Credentials Grant (Enterprise)

Step 1: Box Developer Console Setup

1. Go to Box Developer Console: https://developer.box.com/

2. Create Custom App:

   • Click "Create New App"
   • Select "Custom App"
   • Choose "Server Authentication (Client Credentials Grant)"
   • Name your app (e.g., "MCP Box Server Enterprise")

3. Configure CCG Settings:

   • Application Scopes: Select enterprise permissions needed
   • Enterprise ID: Note your enterprise ID
   • Submit for Approval: Enterprise admin must approve

4. Get Credentials:

   • Copy Client ID
   • Copy Client Secret
   • Copy Enterprise ID

Step 2: Configure Your .env File

# CCG Configuration
AUTH_TYPE=ccg
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
BOX_ENTERPRISE_ID=your_enterprise_id

# Server Configuration
MCP_TRANSPORT=stdio
LOG_LEVEL=info
NODE_ENV=production

Step 3: Enterprise Admin Approval

• Enterprise admin must approve the app in Box Admin Console
• Once approved, server will authenticate automatically

Integration Guides

Claude Code Integration

Add this MCP server to Claude Code for seamless Box integration:

1. Build the server:

   npm run build
   

2. Add to Claude Code configuration:

   Option A: Via Claude Code UI

   • Open Claude Code settings
   • Navigate to "MCP Servers"
   • Add new server with these settings:
     • Name: box-mcp-server
     • Command: node
     • Args: ["/Users/your-username/path-to/mcp-box/dist/index.js"]
     • Environment Variables: Add your .env variables

   Option B: Edit Claude Code config file

   {
     "mcpServers": {
       "box-mcp-server": {
         "command": "node",
         "args": ["/Users/your-username/path-to/mcp-box/dist/index.js"],
         "env": {
           "AUTH_TYPE": "oauth",
           "BOX_CLIENT_ID": "your_client_id",
           "BOX_CLIENT_SECRET": "your_client_secret"
         }
       }
     }
   }
   

3. Restart Claude Code and verify the server appears in MCP servers list

4. Test the integration:

   @box-mcp-server List my recent Box files
   @box-mcp-server Analyze the quarterly report in folder "Reports/2024"
   @box-mcp-server Share the presentation with my team
   

Claude Desktop Integration

For Claude Desktop, add to your MCP configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "box-mcp-server": {
      "command": "node",
      "args": ["/path/to/mcp-box/dist/index.js"],
      "env": {
        "AUTH_TYPE": "oauth",
        "BOX_CLIENT_ID": "your_client_id",
        "BOX_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Other MCP Clients

The server supports standard MCP transports:

STDIO (Default):

node dist/index.js

HTTP with Server-Sent Events:

MCP_TRANSPORT=http MCPSERVER_PORT=3000 AUTH_TOKEN=your_secret node dist/index.js

Usage Examples

Document Management

// Save multiple documents with organization
{
  "name": "box_save_documents",
  "arguments": {
    "documents": [
      {
        "content": "Meeting notes content...",
        "path": "Projects/2024/Q4/meeting-notes.md",
        "metadata": { "classification": "Internal" }
      }
    ],
    "options": {
      "createFolders": true,
      "shareSettings": { "createLink": true, "linkAccess": "company" }
    }
  }
}

AI-Powered Analysis

// Analyze document with Box AI
{
  "name": "box_analyze_document",
  "arguments": {
    "path": "Contracts/partnership-agreement.pdf",
    "analysisType": "qa",
    "options": {
      "questions": ["What are the key payment terms?", "When does this contract expire?"]
    }
  }
}

Smart Search

// Natural language search
{
  "name": "box_search_content",
  "arguments": {
    "query": "quarterly financial reports from 2024 with revenue data",
    "filters": {
      "extensions": ["pdf", "xlsx"],
      "dateRange": { "from": "2024-01-01" },
      "includeContent": true
    }
  }
}

MCP Protocol Support

This server implements the full MCP specification (v2025-06-18):

• ✅ Tools - 8 intent-based tools with structured input/output
• ✅ Resources - 6 Box URI templates for LLM context
• ✅ Prompts - 5 interactive templates for common workflows
• ✅ Transports - STDIO and HTTP/SSE support
• ✅ Authentication - Bearer token support for HTTP transport
• ✅ Error Handling - Comprehensive error responses with user-friendly messages

Development

Running Tests

# Unit + Integration tests
npm test

# E2E tests (requires Box credentials)
npm run test:e2e

# Test coverage
npm run test:coverage

Development Server

# Watch mode with hot reload
npm run dev

# Debug mode with verbose logging
LOG_LEVEL=debug npm start

Project Structure

mcp-box/
├── src/
│   ├── server.ts           # MCP server implementation
│   ├── index.ts           # Entry point & transport setup
│   ├── types.ts           # TypeScript definitions
│   ├── box/               # Box API client
│   └── tools/             # Individual MCP tools
├── tests/                 # Test suites
├── docs/                  # Planning documentation
└── dist/                  # Compiled JavaScript

API Reference

Tools

Resources

Prompts

Troubleshooting

Authentication Issues

OAuth 2.0 Troubleshooting

• Browser doesn't open automatically?

  # Manual OAuth URL will be displayed in console
  # Copy and paste into browser
  

• "Invalid redirect URI" error?
  • Check Box app configuration matches your server settings
  • Ensure redirect URI is exactly: http://localhost:3000/auth/callback
  • Verify no trailing slashes or extra characters
• "Access denied" during login?
  • Check Box app has correct scopes enabled
  • Verify user has access to requested files/folders
  • Ensure app is not disabled in Box Admin Console
• Tokens not persisting?
  • Check file system permissions for token storage
  • Verify .env file has correct credentials
  • Try deleting stored tokens and re-authenticating

CCG Troubleshooting

• CCG Setup: Verify enterprise ID and app approval status
• "App not authorized" error?
  • Enterprise admin must approve app in Box Admin Console
  • Check enterprise ID matches exactly
  • Verify app has required scopes enabled
• Token Refresh: Check credential storage permissions

General Auth Issues

• "Invalid client" errors: Double-check Client ID and Client Secret
• "Unauthorized" responses: Verify auth method matches Box app type
• Token refresh failures: Check network connectivity and Box API status

Common Errors

• File Not Found: Use box_search_content to find correct file paths
• Permission Denied: Verify Box app scopes and user permissions
• Rate Limits: Server handles throttling automatically with exponential backoff

Debugging

# Enable debug logging
LOG_LEVEL=debug node dist/index.js

# Test MCP protocol compliance
npm run test:contract

# Validate Box API connectivity
npm run test:integration

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Follow TDD: Write tests first, then implementation
4. Ensure all tests pass: npm test
5. Update documentation as needed
6. Submit a pull request

License

MIT License - see file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Box API: Box Developer Documentation
• MCP Protocol: MCP Specification

Secure document management meets AI - Keep your files in Box cloud while enabling powerful AI interactions through the Model Context Protocol.