📌Overview

Purpose: The box-mcp-server framework aims to facilitate seamless integration with Box's API for efficient file management and retrieval through user authentication.

Overview: box-mcp-server is a Node.js application that allows developers to interact with Box file storage using JSON Web Token (JWT) or developer token for authentication. It enables capabilities such as searching files and reading supported file types like PDF and Word.

Key Features:

Authentication Options: The framework supports both JWT for persistent connections and developer tokens for quick setups, catering to different application needs.
File Management Capabilities: Enables searching and reading various file types (e.g., PDF, Word), providing essential functionality for applications interacting with Box.

box-mcp-server

Usage

You will need:

BOX_USER_ID

and one of the following:

BOX_JWT_BASE64 (recommended)
BOX_JWT_CONFIG_PATH
BOX_JWT

Auth

JSON Web Token (JWT) Authorization (recommended)

How to get a JWT

Using a JWT Config allows 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 signing up).

Visit 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 will 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.
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 modify these settings.

Base64 encoding JWT

To encode your JWT in Base64, use the following command in your 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 outputs the Base64 encoded JWT which you can then use in your 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 (easiest)

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

Set the BOX_DEV_TOKEN to a Box Developer Token.

Create a new application in the Box Developer Console. The authorization type does not currently matter, as all support Box Developer Token.

Once the 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"
      }
    }
  }
}

Capabilities

Searching files
Reading files

PDF
Word
Others

Development

Prerequisites

Ensure you have the following installed:

Node.js (recommended v22 or higher)
npm
git
dotenv

Setting up Development Environment

Fork the repository
This creates your own copy of the repository under your GitHub account.

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

Copy the dotenv file:
```
cp .env.template .env
```
Install dependencies:
```
npm install
```
Run watch to keep index.js updated:
```
npm run watch
```

Start the model context protocol development server:

dotenv 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.