MCP サーバーボックス

説明

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

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

実装されたツール

Box APIツール

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、DESCRIPTION、FILE_CONTENT、COMMENTS、TAG)。

  • ancestor_folder_ids (List[str], オプション): 検索するフォルダー ID のリスト。

• **返り値:**検索結果は改行で区切られたファイル名と ID のリストとして返されます。

box_read_tool

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

パラメータ:

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

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

box_ask_ai_tool

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

パラメータ:

• file_id (str): ファイルのID

• prompt (str): AIへの質問

戻り値: AI応答

box_hubs_ask_ai_tool

Box AIにハブについて問い合わせてください。現在、API経由でハブIDを取得する方法はないため、このツールを使用するにはIDが必要です。この問題は今後修正される予定です。

パラメータ:

• hubs_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

=======

• パラメータ:

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

• **戻り値:**ファイルのテキスト コンテンツ。

box_ask_ai_tool

単一ファイルに関するクエリボックス AI。

• パラメータ:

  • file_id (str): ファイル識別子。

  • prompt (str): AIに対するクエリまたは指示。

• **戻り値:**ファイルの内容に基づいた AI 応答。

box_ask_ai_tool_multi_file

複数のファイルを使用して Box AI をクエリします。

• パラメータ:

  • file_ids (List[str]): ファイルIDのリスト。

  • prompt (str): 集約されたコンテンツに基づいた AI への指示。

• **戻り値:**提供されたすべてのファイルを考慮して AI が生成した回答。

box_search_folder_by_name

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

• パラメータ:

  • folder_name (str): フォルダーの名前。

• **返される値:**一致するフォルダーに関する情報 (名前と ID)。

box_ai_extract_data

AI を使用してファイルから特定のフィールドを抽出します。

• パラメータ:

  • file_id (str): ファイルのID。

  • fields (str): 抽出するフィールドのカンマ区切りリスト。

• 戻り値: JSON 文字列形式で抽出されたデータ。

box_list_folder_content_by_folder_id

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 (ルートの場合はデフォルトは「0」)。

  • description (str, オプション): フォルダーの説明 (更新用)。

  • recursive (bool、オプション): 再帰的な削除の場合。

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

box_upload_file_from_path_tool

ローカルファイルシステムのパスから Box にファイルをアップロードします。

• パラメータ:

  • file_path (str): ローカルファイルパス。

  • folder_id (str、オプション): 宛先フォルダー ID (デフォルトは "0")。

  • new_file_name (str、オプション): 新しいファイル名 (指定されていない場合は元のファイル名が使用されます)。

• **返される値:**アップロードされたファイルの詳細 (ID と名前) またはエラー メッセージ。

box_upload_file_from_content_tool

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

• パラメータ:

  • content (str | bytes): アップロードするコンテンツ (テキストまたはバイナリ)。

  • file_name (str): ファイルに割り当てる名前。

  • folder_id (str、オプション): 宛先フォルダー ID (デフォルトは "0")。

  • is_base64 (bool、オプション): 提供されたコンテンツが base64 でエンコードされているかどうかを示します。

• **返される値:**ファイル ID と名前を含むアップロード成功メッセージ。

box_download_file_tool

Box からファイルをダウンロードします。

• パラメータ:

  • file_id (str): ダウンロードするファイルの ID。

  • save_file (bool、オプション): ファイルをローカルに保存するかどうか。

  • save_path (str、オプション): ファイルを保存するローカ�� パス。

• **戻り値:**テキスト ファイルの場合はコンテンツを返します。画像の場合は base64 でエンコードされたデータを返します。その他の種類の場合はエラーまたは保存確認メッセージを返します。

Boxドキュメント生成ツール

box_docgen_create_batch_tool

Box Doc Gen テンプレートとローカル JSON ファイルを使用してドキュメントを生成します。

• パラメータ:

  • file_id (str): テンプレートファイルID。

  • destination_folder_id (str): 生成されたドキュメントを保存するフォルダー ID。

  • user_input_file_path (str): 入力データを含む JSON ファイルへのパス。

  • output_type (str、オプション): 出力形式 (デフォルトは "pdf")。

• **戻り値:**ドキュメント生成バッチの結果を JSON 文字列として返します。

box_docgen_get_job_tool

ID で単一の Doc Gen ジョブを取得します。

• パラメータ:

  • job_id (str): ジョブ識別子。

• 戻り値: JSON 形式の文字列でジョブの詳細を返します。

box_docgen_list_jobs_tool

現在のユーザーに関連付けられているすべての Doc Gen ジョブを一覧表示します。

• パラメータ:

  • marker (str | None、オプション): ページ区切りマーカー。

  • limit (int | None、オプション): 返されるジョブの最大数。

• **戻り値:**きれいに印刷された JSON 形式のページ区切りのジョブ リスト。

box_docgen_list_jobs_by_batch_tool

特定のバッチに属する Doc Gen ジョブを一覧表示します。

• パラメータ:

  • batch_id (str): バッチ識別子。

  • marker (str | None、オプション): ページ区切りマーカー。

  • limit (int | None、オプション): 返されるジョブの最大数。

• 戻り値: JSON 形式でのバッチ ジョブの詳細。

box_docgen_template_create_tool

ファイルを Box Doc Gen テンプレートとしてマークします。

• パラメータ:

  • file_id (str): テンプレートとしてマークするファイル ID。

• **戻り値:**マーク後のテンプレートの詳細。

box_docgen_template_list_tool

利用可能なすべての Box Doc Gen テンプレートを一覧表示します。

• パラメータ:

  • marker (str | None、オプション): ページ区切りマーカー。

  • limit (int | None、オプション): リストするテン���レートの最大数。

• 戻り値: JSON 形式のテンプレートのリスト。

box_docgen_template_delete_tool

ファイルから Doc Gen テンプレートのマークを削除します。

• パラメータ:

  • template_id (str): テンプレート識別子。

• **戻り値:**削除の確認を JSON として返します。

box_docgen_template_get_by_id_tool

特定の Doc Gen テンプレートの詳細を取得します。

• パラメータ:

  • template_id (str): テンプレート識別子。

• 戻り値: JSON 形式のテンプレートの詳細。

box_docgen_template_list_tags_tool

Box Doc Gen テンプレートに関連付けられているすべてのタグを一覧表示します。

• パラメータ:

  • template_id (str): テンプレート ID。

  • template_version_id (str | None、オプション): 特定のバージョン ID。

  • marker (str | None、オプション): ページ区切りマーカー。

  • limit (int | None、オプション): 返されるタグの最大数。

• 戻り値: JSON 形式のタグのリスト。

box_docgen_template_list_jobs_tool

特定のテンプレートを使用したすべての Doc Gen ジョブを一覧表示します。

• パラメータ:

  • template_id (str): テンプレート識別子。

  • marker (str | None、オプション): ページ区切りマーカー。

  • limit (int | None、オプション): リストするジョブの最大数。

• **戻り値:**テンプレートのジョブの詳細を JSON 文字列として返します。

要件

• 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.2 ウィンドウズ

   # 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を編集します。

   code ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 設定を追加します:

   { "mcpServers": { "mcp-server-box": { "command": "uv", "args": [ "--directory", "/Users/anovotny/Desktop/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }

3. Claude が実行中の場合は再起動します。

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

1. カーソルを使用して IDE を開きます。

2. 設定で、 Cursor settingsを選択します。

3. 左側のナビゲーションで、 MCPを選択します。

4. 左上で、 Add new global MCP serverクリックします。

5. 次の JSON を貼り付けます (ローカル値に更新してください)。

   { "mcpServers": { "box": { "command": "uv", "args": [ "--directory", "/Users/shurrey/local/mcp-server-box", "run", "src/mcp_server_box.py" ] } } }

6. mcp.json ファイルを保存して閉じ、必要に応じて再起動します。

テストの実行

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

テストの設定

1. ファイルとフォルダのIDを更新します:

   • 各テスト ファイル ( tests/ディレクトリ内) は、Box ファイルとフォルダーのハードコードされた ID を使用します。

   • これらの ID を Box アカウントの有効な ID に置き換えます。

2. ファイルID参照:

   • たとえば、 tests/test_box_api_read.pyでは、 "1728677291168"を有効なファイル 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 : ファイルのアップロードとダウンロード操作をテストします。

• 追加のテストでは、フォルダー操作と Doc Gen 機能がカバーされます。

トラブルシューティング

Claude Desktop を使用して MCP サーバーを実行しているときに MacOS でError: spawn uv ENOENTエラーが表示される場合は、次の操作を実行してください。

• uvを削除してHomebrewで再インストールする: brew install uv

• または、設定で uv 実行可能ファイルへのフルパスを指定します。

  /Users/shurrey/.local/bin/uv --directory /Users/shurrey/local/mcp-server-box run src/mcp_server_box.py

[!NOTE] .env内の Box API 資格情報が正しく設定されていることを確認してください。