box

This MCP server integrates with Box to enable programmatic access to your Box content. It supports authentication via JSON Web Token (JWT) or a Box Developer Token for development workflows. The server exposes capabilities such as searching files and reading file contents, with support for common document types like PDFs and Word documents. To run it, you’ll typically start the server via npm/npx with environment variables that provide the Box credentials (BASE64-encoded JWT or a developer token). Once running, you can connect to the MCP inspector or your orchestration layer to leverage the box-mcp-server’s search and read operations within your Box enterprise or developer account.

Prerequisites:

• Node.js (recommended v22 or higher)
• npm
• git
• dotenv (for local development usage)

1. Install dependencies and set up environment:

   • Ensure Node.js and npm are installed on your machine.

   • Clone the repository (if you’re implementing locally):

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

2. Install dependencies:

   npm install

3. Prepare environment variables

   • Create a .env file or provide environment variables when launching:
     • BOX_USER_ID: Your Box user ID
     • BOX_JWT_BASE64: Base64-encoded JWT configuration (recommended)
     • Alternatively, BOX_DEV_TOKEN for development workflows

4. Run the server (example using npx):

   npx box-mcp-server

5. Optional: run with explicit path via the inspector (if using MCP inspector in development):

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

Notes:

• If using JWT, ensure the Box application is configured for JSON Web Token access and that you’ve generated the appropriate keypair.
• If using a developer token, be mindful that it expires (usually after 60 minutes) and refresh as needed.

Tips and common issues:

• Ensure BOX_USER_ID is set; it's required for Box API calls.
• If using JWT, BASE64 encoding is recommended; this can be generated by encoding your box-jwt-config.json and supplying BOX_JWT_BASE64.
• When using BOX_JWT_CONFIG_PATH or BOX_JWT, only one of these should be actively provided alongside BOX_USER_ID.
• For development, BOX_DEV_TOKEN is the simplest option, but remember it expires and should be refreshed regularly.
• If you encounter authentication failures, re-check Box application permissions: App + Enterprise Access and API calls with as-user header may need reauthorization after config changes.
• The server currently supports searching and reading files, including PDFs and Word documents; check README capabilities section for exact supported types.