https://github.com/hmk/box-mcp-server
A Box model context protocol server to search, read and access files
https://github.com/hmk/box-mcp-server
Last synced: 26 days ago
JSON representation
A Box model context protocol server to search, read and access files
- Host: GitHub
- URL: https://github.com/hmk/box-mcp-server
- Owner: hmk
- License: bsd-3-clause
- Created: 2024-12-31T00:49:10.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-08-22T14:46:26.000Z (about 2 months ago)
- Last Synced: 2025-08-22T16:47:19.577Z (about 2 months ago)
- Language: JavaScript
- Homepage:
- Size: 215 KB
- Stars: 9
- Watchers: 1
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - box-mcp-server - An MCP server that integrates Box cloud storage, enabling file listing, reading, and searching through the Model Context Protocol. ([Read more](/details/box-mcp-server.md)) `box` `cloud-storage` `file-access` `mcp` (File Management MCP Servers)
- awesome-mcp-list - hmk/box-mcp-server - mcp-server?style=social)](https://github.com/hmk/box-mcp-server): Provides listing, reading and searching files on Box. (Uncategorized / Uncategorized)
- awesome-mcp-zh - hmk/box-mcp-server
- awesome-mcp-servers - hmk/box-mcp-server - Box integration for listing, reading and searching files (Legend / 📂 <a name="file-systems"></a>File Systems)
- awesome-mcp-servers - hmk/box-mcp-server - Box integration for listing, reading and searching files (Legend / 📂 <a name="file-systems"></a>File Systems)
- Awesome-MCP-Servers-directory - Box - File access and search for Box (Cloud Storage)
- awesome-mcp-servers - Box - File access and search for Box. (Community Servers)
- awesome-mcp-servers - Box MCP Server - A Box model context protocol server to search, read and access files (Table of Contents / Other Tools and Integrations)
- awesome-mcp-servers - Box MCP Server - A Box model context protocol server to search, read and access files (Table of Contents / Other Tools and Integrations)
- mcp-index - Box - Access and manage files stored in Box, enabling users to search and read content from PDF and Word documents. (Cloud Services)
README
# 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](https://account.box.com/signup/n/developer) (make sure you are signed out of Box before clicking that link).
Visit the [Box Developer Console](https://app.box.com/developers/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:
1. give the application `App + Enterprise Access`, and
2. 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**.
#### Base64 encoding JWT
To encode your JWT in Base64, you can use the following command in your terminal:
```sh
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 then use in your environment variables.
#### Claude Desktop Configuration
```json
{
"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 will only last 60 minutes.
To get started, set the `BOX_DEV_TOKEN` to a [Box Developer Token](https://developer.box.com/guides/authentication/tokens/developer-tokens/).
Begin 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.
Once your application is created, navigate to its configuration setings and click `Generate Developer Token`.
#### Claude Desktop Configuration
```json
{
"mcpServers": {
"box": {
"command": "npx",
"args": ["box-mcp-server"],
"env": {
"BOX_DEV_TOKEN": "YOUR_DEV_TOKEN_GOES_HERE"
}
}
}
}
```
## Capabilities
1. Searching files
2. Reading files
- [x] PDF
- [x] Word
- [ ] Others
## Development
### Prerequisites
Before you begin, ensure you have the following installed:
- Node.js (recommended v22 or higher)
- npm
- git
- dotenv
### Setting up Development Environment
To set up the development environment, follow these steps:
1. 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
1. Clone Your Fork:
```sh
git clone https://github.com/YOUR_USERNAME/box-mcp-server.git
cd box-mcp-server
```
1. Add Upstream Remote
```sh
git remote add upstream https://github.com/hmk/box-mcp-server.git
```
1. Copy the dotenv file
```sh
cp .env.template .env
```
1. Install dependencies:
```sh
npm install
```
1. Run watch to keep index.js updated:
```sh
npm run watch
```
1. Start the model context protocol development server:
```sh
dotenv npx @modelcontextprotocol/inspector node PATH_TO_YOUR_CLONED_REPO/dist/index.js
```
1. 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.