box-mcp-server

Usage

JSON Web Token (JWT) Authorization (recommended)

Using a JWT Config will allow persistent connection to Box. You will need a paid Box enterprise account, or you can sign up for a free developer account (make sure you are signed out of Box before clicking that link).

Begin by visiting the Box Developer Console and create a new application. Make sure the authorization type is JSON Web Token.

Go to Configuration > Add and Manage Public Keys and Generate a Public/Private Keypair. If you have not already, Box prompt you to set up 2 factor authentication and Authorize the application as an administrator in your box account. You will need to:

give the application App + Enterprise Access, and
enable the make API calls using the as-user header option

via the Box Application's Configuration page. Make sure to reauthorize the application if you are modifying these settings.

Download/store the configuration JSON somewhere on your computer. We will set the environment variable BOX_JWT_CONFIG_PATH to its location. We will also set the BOX_USER_ID to the user whose files we will be accessing. You can find your own Box User Id on your account page. You can also set the BOX_JWT environment variable to the JSON itself (as an alternative to the path).

Claude Desktop Configuration

{
  "mcpServers": {
    "box": {
      "command": "npx",
      "args": ["box-mcp-server"],
      "env": {
        "BOX_JWT_CONFIG_PATH": "/path/to/your/box-jwt-config.json",
        "BOX_USER_ID": "123456"
      }
    }
  }
}

Developer Token Authorization (easiest)

Using a developer token is the easiest way to integrate with Box, but will only last 60 minutes.

To get started, set the BOX_DEV_TOKEN to a Box Developer Token.

Begin by visiting the Box Developer Console and create a new application. The authorization type does not currently matter, as all support Box Developer Token.

Once your application is created, navigate to its configuration setings 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"
      }
    }
  }
}

Capabilities

Searching files
Reading files

PDF
Word
Others

Development

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v22 or higher)
npm
git

Setting up Development Environment

To set up the development environment, follow these steps:

Fork the repository
- Click the "Fork" button in the top-right corner of this repository
- This creates your own copy of the repository under your Github acocunt
Clone Your Fork:
git clone https://github.com/YOUR_USERNAME/box-mcp-server.git cd box-mcp-server
Add Upstream Remote
git remote add upstream https://github.com/hmk/box-mcp-server.git
Install dependencies:
npm install
Set the BOX_DEV_TOKEN environment variable:
export BOX_DEV_TOKEN=your_developer_token
Run watch to keep index.js updated:
npm run watch
Start the model context protocol development server:
npx @modelcontextprotocol/inspector node PATH_TO_YOUR_CLONED_REPO/dist/index.js
If the development server did not load the environment variable correctly, set the BOX_DEV_TOKEN on the left-hand side of the mcp inspector.