Box云存储MCP服务器

Box MCP服务器

一种模型上下文协议（MCP）服务器，提供对Box云存储的安全访问，而无需本地文件持久性。该服务器使大型语言模型能够通过标准化的MCP接口与Box文件、文件夹和AI功能进行交互。

特性

🔧 8个核心工具（基于意图）

• box_save_documents -通过自动文件夹创建批量上传文档
• box_read_document -无需本地存储即可流式传输文档内容
• box_manage_folders -创建和组织文件夹结构
• box_explore_storage -使用筛选浏览Box目录树
• box_share_content -创建共享链接并管理协作
• box_analyze_document -使用Box AI进行文档分析、问答和提取
• box_search_content -具有高级过滤功能的自然语言搜索
• box_retrieve_documents -批量检索，可选本地保存

📚 MCP资源（6个URI模板）

• box://file/{fileId} -按ID访问特定的Box文件
• box://folder/{folderId} -按ID访问特定的Box文件夹
• box://search?q={query} -带有查询参数的搜索框内容
• box://user/storage -当前用户的存储配额和使用情况
• box://user/recent -最近访问的文件
• box://folder/root/tree -从根目录开始完成文件夹结构

💬 MCP提示（5个交互式模板）

• share_file -创建具有可自定义权限的共享链接
• analyze_document -使用Box AI分析具有特定提示的文档
• organize_folder -使用不同的策略（按日期、类型、名称）组织文件
• bulk_upload -上传多个文件夹组织的文件
• collaboration_setup -与特定用户和角色建立协作

🔒 安全与合规

• 零本地存储 -所有文档都保留在Box云中
• 多身份验证支持 -OAuth 2.0、客户端凭据授予（CCG）、JWT
• 加密凭据 -安全的令牌存储和自动刷新
• 企业级 -利用Box的企业安全功能

快速开始

先决条件

1. Box开发者帐户 - 在Box开发者控制台创建
2. Node.js 18+ - 下载Node.js
3. Box应用程序配置 -OAuth 2.0或客户端凭据授予应用程序

安装

# Clone and install
git clone https://github.com/your-org/mcp-box
cd mcp-box
npm install

# Build the server
npm run build

配置

创建一个 .env 项目根目录中的文件：

# Authentication Method (oauth | ccg)
AUTH_TYPE=oauth

# Box App Credentials
BOX_CLIENT_ID=your_client_id_here
BOX_CLIENT_SECRET=your_client_secret_here
BOX_ENTERPRISE_ID=your_enterprise_id_here  # Required for CCG

# Server Configuration
MCP_TRANSPORT=stdio              # stdio | http
LOG_LEVEL=info                   # debug | info | warn | error
NODE_ENV=development

身份验证设置

OAuth 2.0（建议个人使用）

步骤1:Box开发人员控制台设置

1. 转到Box开发人员控制台: https://developer.box.com/

2. 创建自定义应用程序:

   • 点击“创建新应用”
   • 选择“自定义应用程序”
   • 选择 “用户身份验证（OAuth 2.0）”
   • 命名您的应用程序（例如，“MCP Box Server”）

3. 配置OAuth设置:

   • 重定向URI: http://localhost:3000/auth/callback
   • 应用范围：选择所有需要的权限：
     • ✅ 读取所有文件和文件夹
     • ✅ 写入所有文件和文件夹
     • ✅ 管理用户
     • ✅ 管理企业财产
   • 保存 您的配置

4. 获取凭据:

   • 复制 客户端ID
   • 复制 客户端密钥

步骤2：配置.env文件

# OAuth 2.0 Configuration
AUTH_TYPE=oauth
BOX_CLIENT_ID=your_client_id_here
BOX_CLIENT_SECRET=your_client_secret_here

# Server Configuration
MCP_TRANSPORT=stdio
LOG_LEVEL=info
NODE_ENV=development

步骤3：首次身份验证

# Build and start the server
npm run build
npm start

发生了什么：

1. 服务器未检测到存储的OAuth令牌
2. 自动打开浏览器到Box登录页面
3. 您使用Box凭据登录
4. Box使用授权码重定向回
5. 服务器交换访问/刷新令牌的代码
6. 代币被安全地存储以备将来使用

客户端凭据授予（企业）

步骤1:Box开发人员控制台设置

1. 转到Box开发人员控制台: https://developer.box.com/

2. 创建自定义应用程序:

   • 点击“创建新应用”
   • 选择“自定义应用程序”
   • 选择 “服务器身份验证（客户端凭据授予）”
   • 命名您的应用程序（例如，“MCP Box Server Enterprise”）

3. 配置CCG设置:

   • 应用范围：选择所需的企业权限
   • 企业ID：记下您的企业ID
   • 提交审批：企业管理员必须批准

4. 获取凭据:

   • 复制 客户端ID
   • 复制 客户端密钥
   • 复制 企业ID

步骤2：配置.env文件

# CCG Configuration
AUTH_TYPE=ccg
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
BOX_ENTERPRISE_ID=your_enterprise_id

# Server Configuration
MCP_TRANSPORT=stdio
LOG_LEVEL=info
NODE_ENV=production

步骤3：企业管理员审批

• 企业管理员必须在Box管理控制台中批准应用程序
• 一旦获得批准，服务器将自动进行身份验证

集成指南

Claude代码集成

将此MCP服务器添加到Claude Code中，以实现无缝的Box集成：

1. 构建服务器：

   复制

   npm run build
   

2. 添加到Claude代码配置：

   选项A：通过克劳德代码UI

   • 打开克劳德代码设置
   • 导航到“MCP服务器”
   • 使用以下设置添加新服务器：
     • 名字: box-mcp-server
     • 命令: node
     • 参数: ["/Users/your-username/path-to/mcp-box/dist/index.js"]
     • 环境变量：添加您的 .env 变量

   选项B：编辑Claude代码配置文件

   复制

   {
     "mcpServers": {
       "box-mcp-server": {
         "command": "node",
         "args": ["/Users/your-username/path-to/mcp-box/dist/index.js"],
         "env": {
           "AUTH_TYPE": "oauth",
           "BOX_CLIENT_ID": "your_client_id",
           "BOX_CLIENT_SECRET": "your_client_secret"
         }
       }
     }
   }
   

3. 重新启动Claude代码 并验证服务器是否出现在MCP服务器列表中

4. 测试集成：

   复制

   @box-mcp-server List my recent Box files
   @box-mcp-server Analyze the quarterly report in folder "Reports/2024"
   @box-mcp-server Share the presentation with my team
   

Claude桌面集成

对于Claude Desktop，请在MCP配置中添加：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "box-mcp-server": {
      "command": "node",
      "args": ["/path/to/mcp-box/dist/index.js"],
      "env": {
        "AUTH_TYPE": "oauth",
        "BOX_CLIENT_ID": "your_client_id",
        "BOX_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

其他MCP客户端

服务器支持标准MCP传输：

STDIO（默认）：

node dist/index.js

带有服务器发送事件的HTTP：

MCP_TRANSPORT=http MCPSERVER_PORT=3000 AUTH_TOKEN=your_secret node dist/index.js

使用示例

文档管理

// Save multiple documents with organization
{
  "name": "box_save_documents",
  "arguments": {
    "documents": [
      {
        "content": "Meeting notes content...",
        "path": "Projects/2024/Q4/meeting-notes.md",
        "metadata": { "classification": "Internal" }
      }
    ],
    "options": {
      "createFolders": true,
      "shareSettings": { "createLink": true, "linkAccess": "company" }
    }
  }
}

AI驱动的分析

// Analyze document with Box AI
{
  "name": "box_analyze_document",
  "arguments": {
    "path": "Contracts/partnership-agreement.pdf",
    "analysisType": "qa",
    "options": {
      "questions": ["What are the key payment terms?", "When does this contract expire?"]
    }
  }
}

智能搜索

// Natural language search
{
  "name": "box_search_content",
  "arguments": {
    "query": "quarterly financial reports from 2024 with revenue data",
    "filters": {
      "extensions": ["pdf", "xlsx"],
      "dateRange": { "from": "2024-01-01" },
      "includeContent": true
    }
  }
}

MCP协议支持

此服务器实现了完整的MCP规范（v2025-06-18）：

• ✅ 工具 -8个基于意图的工具，具有结构化的输入/输出
• ✅ 资源 -LLM上下文的6个Box URI模板
• ✅ 提示 -5个用于常见工作流的交互式模板
• ✅ 运输 -STDIO和HTTP/SSE支持
• ✅ 认证 -HTTP传输的承载令牌支持
• ✅ 错误处理 -全面的错误响应和用户友好的消息

发展

运行测试

# Unit + Integration tests
npm test

# E2E tests (requires Box credentials)
npm run test:e2e

# Test coverage
npm run test:coverage

开发服务器

# Watch mode with hot reload
npm run dev

# Debug mode with verbose logging
LOG_LEVEL=debug npm start

项目结构

mcp-box/
├── src/
│   ├── server.ts           # MCP server implementation
│   ├── index.ts           # Entry point & transport setup
│   ├── types.ts           # TypeScript definitions
│   ├── box/               # Box API client
│   └── tools/             # Individual MCP tools
├── tests/                 # Test suites
├── docs/                  # Planning documentation
└── dist/                  # Compiled JavaScript

api参考

工具

资源

提示

故障排除

身份验证问题

OAuth 2.0故障排除

• 浏览器不会自动打开吗？
  复制

  # Manual OAuth URL will be displayed in console
  # Copy and paste into browser
  

• “重定向URI无效”错误？
  • 复选框应用程序配置与您的服务器设置匹配
  • 确保重定向URI准确： http://localhost:3000/auth/callback
  • 验证没有尾随斜线或额外字符
• 登录时“拒绝访问”？
  • 复选框应用程序已启用正确的作用域
  • 验证用户是否有权访问请求的文件/文件夹
  • 确保应用程序未在Box管理控制台中禁用
• 令牌不持久？
  • 检查令牌存储的文件系统权限
  • 验证 .env 文件具有正确的凭据
  • 尝试删除存储的令牌并重新进行身份验证

CCG故障排除

• CCG设置：验证企业ID和应用程序审批状态
• “应用程序未授权”错误？
  • 企业管理员必须在Box管理控制台中批准应用程序
  • 检查企业ID是否完全匹配
  • 验证应用程序是否启用了所需的作用域
• 令牌刷新：检查凭据存储权限

一般授权问题

• “无效客户端”错误：仔细检查客户端ID和客户端密码
• “未经授权”的响应：验证身份验证方法是否与Box应用程序类型匹配
• 令牌刷新失败：检查网络连接和Box API状态

常见错误

• 文件未找到：使用 box_search_content 查找正确的文件路径
• 权限不足：验证Box应用程序范围和用户权限
• 速率限制：服务器通过指数回退自动处理节流

调试

# Enable debug logging
LOG_LEVEL=debug node dist/index.js

# Test MCP protocol compliance
npm run test:contract

# Validate Box API connectivity
npm run test:integration

贡献

1. 复刻仓库
2. 创建要素分支： git checkout -b feature-name
3. 遵循TDD：先写测试，然后实现
4. 确保所有测试通过： npm test
5. 根据需要更新文档
6. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• 问题: GitHub问题
• 讨论: GitHub讨论
• API方框: Box开发者文档
• MCP协议: MCP规范

安全文档管理与人工智能 -将您的文件保存在Box云中，同时通过模型上下文协议实现强大的AI交互。