Box MCP Server

🚀 box-mcp-server

This project provides a server for interacting with Box services. It supports different authentication methods and offers functions like file search and reading.

🚀 Quick Start

You need the following:

• BOX_USER_ID

And one of the following:

• BOX_JWT_BASE64 (Recommended)
• BOX_JWT_CONFIG_PATH
• BOX_JWT

✨ Authentication

JSON Web Token (JWT) Authorization (Recommended)

How to Obtain JWT

Using JWT configuration allows for a persistent connection to Box.

You need a paid Box enterprise account, or you can sign up for a free developer account (make sure you're logged out of Box before clicking the link). Visit the Box Developer Console to create a new application. If you haven't set it up, ensure you've set up two-factor authentication and authorized the application as an administrator in your Box account. You need to:

1. Grant the application App + Enterprise Access permissions, and
2. Enable the Make API calls with as-user header option

Through the Box application's configuration page. If you modify these settings, make sure to re-authorize the application.

Base64-Encode JWT

To Base64-encode your JWT, use the following command in the terminal:

cat /path/to/your/box-jwt-config.json | base64

Replace /path/to/your/box-jwt-config.json with the actual path to your JWT configuration file. This will output the Base64-encoded JWT, which you can use for environment variables.

Claude Desktop Configuration

{
  "mcpServers": {
    "box": {
      "command": "npx",
      "args": ["box-mcp-server"],
      "env": {
        "BOX_JWT_BASE64": "YOUR_BASE64_ENCODED_JWT",
        "BOX_USER_ID": "123456"
      }
    }
  }
}

Developer Token Authorization (Simplest)

Using a developer token is the simplest way to integrate with Box, but it only lasts for 60 minutes.

To get started, set BOX_DEV_TOKEN to a Box developer token.

First, visit the Box Developer Console to create a new application. The authorization type doesn't matter at this time because all applications supporting Box developer tokens are supported.

Once your application is created, navigate to its configuration settings and click Generate Developer Token.

Claude Desktop Configuration

{
  "mcpServers": {
    "box": {
      "command": "npx",
      "args": ["box-mcp-server"],
      "env": {
        "BOX_DEV_TOKEN": "YOUR_DEV_TOKEN_GOES_HERE"
      }
    }
  }
}

✨ Features

1. Search for files
2. Read files
   • [x] PDF
   • [x] Word
   • [ ] Others

🔧 Development

Prerequisites

Before you start, make sure you have the following software installed:

• Node.js (Recommended v22 or higher)
• npm
• git
• dotenv

Set Up the Development Environment

To set up the development environment, follow these steps:

1. Fork the repository

   • Click the "Fork" button in the upper right corner of this repository.
   • This will create a copy of the repository under your own GitHub account.

2. Clone your copy:

   git clone https://github.com/YOUR_USERNAME/box-mcp-server.git
   cd box-mcp-server
   

3. Add the upstream remote repository

   git remote add upstream https://github.com/hmk/box-mcp-server.git
   

4. Copy the dotenv file

   cp .env.template .env
   

5. Install dependencies:

   npm install
   

6. Run the watcher to keep index.js updated:

   npm run watch
   

7. Start the Model Context Protocol development server:

   dotenv npx @modelcontextprotocol/inspector node PATH_TO_YOUR_CLONED_REPO/dist/index.js
   

8. If the development server fails to load environment variables correctly, set BOX_DEV_TOKEN on the left side of the mcp inspector.