Box MCP Server

1# box-mcp-server
2 
3![CI](https://github.com/hmk/box-mcp-server/actions/workflows/jest.yml/badge.svg?branch=main)
4 
5## Usage
6 
7You will need:
8 
9- `BOX_USER_ID` 
10 
11and one of the following:
12 
13- `BOX_JWT_BASE64` (recommended)
14- `BOX_JWT_CONFIG_PATH`
15- `BOX_JWT`
16 
17## Auth
18 
19### JSON Web Token (JWT) Authorization (recommended)
20 
21#### How to get a JWT
22 
23Using a JWT Config allows persistent connection to Box.
24 
25 
26You will need a paid Box enterprise account, or you can sign up for a [free developer account](https://account.box.com/signup/n/developer) (make sure you are signed out of Box before clicking that link).
27 
28Visit the [Box Developer Console](https://app.box.com/developers/console) and create a new application. Make sure the authorization type is JSON Web Token.
29 
30Go to `Configuration > Add and Manage Public Keys` and Generate a Public/Private Keypair.
31If 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:
32 
331. give the application `App + Enterprise Access`, and
342. enable the `make API calls using the as-user header` option
35 
36via the Box Application's Configuration page. **Make sure to reauthorize the application if you are modifying these settings**.
37 
38#### Base64 encoding JWT
39 
40To encode your JWT in Base64, you can use the following command in your terminal:
41 
42```sh
43cat /path/to/your/box-jwt-config.json | base64
44```
45 
46Replace `/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 then use in your environment variables.
47 
48#### Claude Desktop Configuration
49 
50```json
51{
52  "mcpServers": {
53    "box": {
54      "command": "npx",
55      "args": ["box-mcp-server"],
56      "env": {
57        "BOX_JWT_BASE64": "YOUR_BASE64_ENCODED_JWT",
58        "BOX_USER_ID": "123456"
59      }
60    }
61  }
62}
63```
64 
65### Developer Token Authorization (easiest)
66 
67Using a developer token is the easiest way to integrate with Box, but will only last 60 minutes.
68 
69To get started, set the `BOX_DEV_TOKEN` to a [Box Developer Token](https://developer.box.com/guides/authentication/tokens/developer-tokens/).
70 
71Begin by visiting the [Box Developer Console](https://app.box.com/developers/console) and create a new application. The authorization type does not currently matter, as all support Box Developer Token.
72 
73Once your application is created, navigate to its configuration setings and click `Generate Developer Token`.
74 
75#### Claude Desktop Configuration
76 
77```json
78{
79  "mcpServers": {
80    "box": {
81      "command": "npx",
82      "args": ["box-mcp-server"],
83      "env": {
84        "BOX_DEV_TOKEN": "YOUR_DEV_TOKEN_GOES_HERE"
85      }
86    }
87  }
88}
89```
90 
91## Capabilities
92 
931. Searching files
942. Reading files
95 
96- [x] PDF
97- [x] Word
98- [ ] Others
99 
100## Development
101 
102### Prerequisites
103 
104Before you begin, ensure you have the following installed:
105 
106- Node.js (recommended v22 or higher)
107- npm
108- git
109- dotenv
110 
111### Setting up Development Environment
112 
113To set up the development environment, follow these steps:
114 
1151. Fork the repository
116 
117   - Click the "Fork" button in the top-right corner of this repository
118   - This creates your own copy of the repository under your Github acocunt
119 
1201. Clone Your Fork:
121 
122   ```sh
123   git clone https://github.com/YOUR_USERNAME/box-mcp-server.git
124   cd box-mcp-server
125   ```
126 
1271. Add Upstream Remote
128   ```sh
129   git remote add upstream https://github.com/hmk/box-mcp-server.git
130   ```
131 
1321. Copy the dotenv file
133    ```sh
134    cp .env.template .env
135    ```
136 
1371. Install dependencies:
138 
139   ```sh
140   npm install
141   ```
142 
1431. Run watch to keep index.js updated:
144 
145   ```sh
146   npm run watch
147   ```
148 
1491. Start the model context protocol development server:
150 
151   ```sh
152   dotenv npx @modelcontextprotocol/inspector node PATH_TO_YOUR_CLONED_REPO/dist/index.js
153   ```
154 
1551. 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.
156