MCP サーバーボックス

説明

MCP Server Boxは、Box APIと統合してファイル検索、テキスト抽出、AIベースのクエリ、データ抽出といった様々な操作を実行するPythonプロジェクトです。box box-sdk-genライブラリを活用し、Boxのファイルやフォルダを操作するためのツールセットを提供します。

モデルコンテキストプロトコル（MCP）は、モデルが様々なデータソースやサービスと連携する方法を標準化するために設計されたフレームワークです。このプロジェクトでは、MCPを用いてBox APIとのシームレスな統合を促進し、Boxのファイルやフォルダに対する効率的でスケーラブルな操作を実現します。MCP Server Boxプロジェクトは、高度なAIと機械学習技術を用いてBoxデータを管理・処理するための堅牢で柔軟なソリューションを提供することを目指しています。

実装されたツール

ボックスツール

box_who_am_i

現在のユーザー情報を取得し、接続状態を確認します。

**戻り値:**ユーザー情報文字列

box_authorize_app_tool

Box アプリケーションの承認プロセスを開始します。

**戻り値:**承認ステータスメッセージ

box_search_tool

Box内のファイルを検索します。

パラメータ:

• query (str): 検索クエリ
• file_extensions (List[str], オプション): フィルタリングするファイル拡張子
• where_to_look_for_query (List[str], オプション): 検索する場所 (NAME, DESCRIPT, FILE_CONTENT, COMMENTS, TAG)
• ancestor_folder_ids （リスト[str]、オプション）: 検索対象となるフォルダID

**戻り値:**検索結果

box_read_tool

Box ファイルのテキスト コンテンツを読み取ります。

パラメータ:

• file_id (str): 読み取るファイルのID

**戻り値:**ファイルの内容

box_ask_ai_tool

Box AI にファイルについて質問します。

パラメータ:

• file_id (str): ファイルのID
• prompt (str): AIへの質問

戻り値: AI応答

box_search_folder_by_name

名前でフォルダーを検索します。

パラメータ:

• folder_name (str): フォルダ名

**戻り値:**フォルダID

box_ai_extract_data

AI を使用してファイルからデータを抽出します。

パラメータ:

• file_id (str): ファイルのID
• fields (str): 抽出するフィールド

戻り値: JSON形式で抽出されたデータ

box_list_folder_content_by_folder_id

フォルダーの内容を一覧表示します。

パラメータ:

• folder_id (str): フォルダのID
• is_recursive (bool): 再帰的にリストするかどうか

戻り値: ID、名前、タイプ、説明を含む JSON 形式のフォルダーの内容

box_manage_folder_tool

Box 内のフォルダーを作成、更新、または削除します。

パラメータ:

• action (str): 実行するアクション: "create"、"delete"、または "update"
• folder_id (str, オプション): フォルダのID (削除/更新に必須)
• name (str, オプション): フォルダ名 (作成の場合は必須、更新の場合はオプション)
• parent_id (str, オプション): 親フォルダID (作成の場合は必須、更新の場合はオプション)
• description (str, オプション): フォルダの説明 (更新の場合はオプション)
• recursive (bool, オプション): 再帰的に削除するかどうか (delete の場合はオプション)

**戻り値:**フォルダの詳細を含むステータスメッセージ

box_upload_file_tool

コンテンツをファイルとして Box にアップロードします。

パラメータ:

• content (str): ファイルとしてアップロードするコンテンツ
• file_name (str): Box内のファイルに付ける名前
• folder_id (任意、オプション): アップロード先のフォルダのID

**戻り値:**ファイルIDと名前を含むアップロードステータス

box_download_file_tool

Box からファイルをダウンロードし、そのコンテンツを返します。

パラメータ:

• file_id (任意): ダウンロードするファイルのID
• save_file (bool, オプション): ファイルをローカルに保存するかどうか
• save_path (str, オプション): ファイルを保存するパス

**戻り値:**テキスト、base64エンコードされた画像、または保存ステータスメッセージとしてのファイルの内容

要件

• Python 3.13以上
• Box API 資格情報 (クライアント ID、クライアント シークレットなど)

インストール

1. リポジトリをクローンします。
   git clone https://github.com/box-community/mcp-server-box.git cd mcp-server-box
2. まだインストールされていない場合は、 uvをインストールします。2.1 MacOS+Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   2.2 ウィンドウズ
   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
3. プロジェクトを作成して設定します。3.1 MacOS+Linux
   # Create virtual environment and activate it uv venv source .venv/bin/activate # Lock the dependencies uv lock
   3.1 ウィンドウズ
   # Create virtual environment and activate it uv venv .venv\Scripts\activate # Lock the dependencies uv lock
4. ルート ディレクトリに.envファイルを作成し、Box API 資格情報を追加します。
   BOX_CLIENT_ID=your_client_id BOX_CLIENT_SECRET=your_client_secret

使用法

MCPサーバーの実行

MCP サーバーを起動するには、次のコマンドを実行します。

クロードをクライアントとして利用する

1. claude_desktop_config .jsonを編集する

2. そして次の行を追加します。

[!NOTE] MacOS を使用している場合は、brew をbrew install uvか、uv 実行可能ファイルへのフル パスを指定します: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

3. クロードが実行中の場合は再起動してください

カーソルをクライアントとして使用する

1. カーソルでIDEを開く
2. 設定で、 Cursor settingsを選択します。
3. 左側のナビゲーションで、 MCPを選択します。
4. 左上で、 Add new global MCP serverを選択します。
5. 次の json を、必ずローカル値に更新してください。

6. mcp.json ファイルを保存して閉じ、MCP サーバーが有効になっていることを確認してください。再起動が必要になる場合があります。

テストの実行

このプロジェクトには、Box APIの機能を検証するための一連のテストが含まれています。テストを実行する前に、テストファイル内のファイルとフォルダのIDをBoxアカウント内のファイルと一致するように更新する必要があります。

テストの設定

1. ファイルとフォルダのIDを更新します:
   • 各テストファイル（ tests/ディレクトリ内）には、BoxファイルとフォルダのハードコードされたIDが含まれています。
   • これらのIDをBoxアカウント内のファイルとフォルダのIDに置き換える必要があります
   • 例: test_box_api_read.pyで、 "1728677291168"を Box アカウント内のファイルの ID に置き換えます。
2. テストファイルID参照:
   • test_box_api_read.py : 有効なドキュメントファイルIDが必要です（例：Word文書）
   • test_box_api_search.py : コンテンツに合わせて検索クエリとファイル拡張子を更新します
   • test_box_api_ai.py : AI抽出機能をテストするためのファイルIDが必要です
   • 他のテストファイルでは、特定のフォルダIDまたはファイルタイプが必要になる場合があります。

テストの実行

ファイル ID を更新したら、pytest を使用してテストを実行できます。

利用可能なテスト

• test_box_auth.py : 認証機能をテストします
• test_box_api_basic.py : 基本的な Box API テスト
• test_box_api_read.py : ファイル読み取り機能をテストします
• test_box_api_search.py : 検索機能をテストします
• test_box_api_ai.py : AIベースの機能をテストする
• test_box_api_file_ops.py : ファイルのアップロードとダウンロード操作をテストします

新しいテストの作成

新しいテストを作成する場合:

1. 既存のテストファイルのパターンに従う
2. 認証されたAPIアクセスにはbox_clientフィクスチャを使用する
3. テスト中に作成されたテストファイルやフォルダをクリーンアップします
4. 機能性を検証するために適切なアサーションを追加する

トラブルシューティング

MacOS で Claude Desktop を使用して MCP サーバーを実行している場合、次のエラーが表示されます。

Error: spawn uv ENOENT

uv を削除して brew で再brew install uvするか、または uv 実行ファイルへのフルパスを指定します: /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py