Box Developerドキュメント
ログイン

セルフホストBox MCPサーバー

ガイド Box MCPサーバー セルフホストBox MCPサーバー

セルフホストBox MCPサーバー

セルフホストBox MCPサーバーとは、さまざまな操作 (ファイル検索、テキスト抽出、AIベースのクエリ実行、データ抽出など) を行うためにBox APIと統合されているPythonプロジェクトです。Box Pythonの次世代SDKライブラリを利用し、Boxのファイルやフォルダを操作するための一連のツールを提供します。

インストール

前提条件

  • Python 3.13以上
  • Box Platformアプリの資格情報 (クライアントID、クライアントシークレット)

セルフホストBox MCPサーバーを設定するには、このセクションの手順に従います。

  1. リポジトリを複製します。
git clone https://github.com/box-community/mcp-server-box.git
cd mcp-server-box
  1. uvがマシンにインストールされていない場合はインストールします。
macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

その後ターミナルを再起動し、uvコマンドが取得されることを確認します。

  1. プロジェクトを作成して設定します。
macOS/Linux
# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Lock the dependencies
uv lock
Windows
# Create virtual environment and activate it
uv venv
.venv\Scripts\activate

# Lock the dependencies
uv lock
  1. ルートディレクトリに.envファイルを作成し、Box Platformアプリの資格情報を入力します。
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret

動画によるチュートリアルを視聴して、Box MCPツールの使用例を確認することもできます。

Box MCPサーバーのローカルでの実行

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

uv --directory /Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box run src/mcp_server_box.py

ローカルの設定が反映されるようにパスを更新します。

CursorをBox MCPクライアントとして使用する

前提条件:

CursorでBox MCPサーバーの使用を開始するには、以下の手順に従います。

  1. Cursorアプリを開きます。
  2. 歯車アイコンをクリックして設定を開きます。
  3. [Cursor Settings] タブで [MCP] を選択します。
  4. [Add new global MCP server] ボタンをクリックします。これにより、mcp.jsonファイルが開きます。
  5. ローカルの設定を使用して値を更新し、次のJSONを貼り付けます。
{
  "mcpServers": {
    "box": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box",
        "run",
        "src/mcp_server_box.py"
      ]
    }
  }
}
  1. mcp.jsonファイルを保存して閉じます。
  2. 必要に応じて、Cursorを再起動します。
  3. box_authorize_app_toolツールを使用して、Box MCPの使用を開始します。

Claude for DesktopをBox MCPクライアントとして使用する

前提条件:

  • Claude for Desktopクライアントをダウンロードする
  • 必要に応じて、VS Codeのcodeコマンドを設定する

Claude for DesktopでBox MCPを設定するには、以下の手順に従います。

  1. claude_desktop_config.jsonを編集します。

ターミナルで次のコマンドを実行します。

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

または、Claudeのメインのナビゲーションで [Settings] を選択します。[Developers] タブを選択し、[Edit Config] をクリックします。これにより、claude_desktop_config.jsonを含むフォルダウィンドウが表示されます。

  1. 構成を追加します。
{
  "mcpServers": {
      "mcp-server-box": {
          "command": "uv",
          "args": [
              "--directory",
              "/Users/Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box",
              "run",
              "src/mcp_server_box.py"
          ]
      }
  }
}
  1. Claude for Desktopを再起動します。
  2. box_authorize_app_toolを使用してBox MCPサーバーを認証します。

利用可能なツール

認証およびユーザーツール

ツール説明パラメータ戻り値
box_who_am_i現在のユーザーの情報を取得し、接続のステータスを確認します。なしユーザー情報の文字列。
box_authorize_app_toolBoxアプリケーションの承認プロセスを開始します。なし承認ステータスメッセージ。

検索およびナビゲーションツール

ツール

説明

パラメータ

戻り値

box_search_tool

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

  • query (str): 検索クエリ。
  • file_extensions (List[str], optional): 拡張子によるフィルタ。
  • where_to_look_for_query (List[str], optional): 検索する場所。
  • ancestor_folder_ids (List[str], optional): 検索を制限するためのフォルダID。

改行で区切られた、ファイル名とIDのリスト

box_search_folder_by_name

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

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

フォルダIDと情報

box_list_folder_content_by_folder_id

フォルダコンテンツのリストを取得します

  • folder_id (str): フォルダのID。

  • is_recursive (bool): 再帰的にリストを取得するかどうか。

JSON形式のフォルダコンテンツ

ファイル操作

ツール

説明

パラメータ

戻り値

box_read_tool

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

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

ファイルコンテンツ

box_upload_file_from_path_tool

ローカルパスからファイルをアップロードします

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

  • folder_id (str, optional): アップロード先フォルダID。

  • new_file_name (str, optional): 新しいファイルの名前。

ファイルの詳細またはエラーメッセージ

box_upload_file_from_content_tool

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

  • content (str|bytes): アップロードするコンテンツ。

  • file_name (str): ファイル名。

  • folder_id (str, optional): アップロード先フォルダID。

  • is_base64 (bool, optional): コンテンツがbase64でエンコードされているかどうか。

アップロードの成功を示すメッセージ

box_download_file_tool

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

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

  • save_file (bool, optional): ローカルに保存するかどうか。

  • save_path (str, optional): ローカルの保存パス。

ファイルコンテンツまたは保存の確認

フォルダ管理

ツール

説明

パラメータ

戻り値

box_manage_folder_tool

フォルダを作成、更新、または削除します

  • action (str): create、delete、またはupdate。
  • folder_id (str, optional): フォルダID。
  • name (str, optional): フォルダ名。
  • parent_id (str, optional): 親フォルダID。
  • description (str, optional): フォルダの説明。
  • recursive (bool, optional): 再帰的な削除かどうか。

フォルダの詳細を含むステータスメッセージ

Box AIのツール

ツール

説明

パラメータ

戻り値

box_ask_ai_tool

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

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

  • prompt (str): AIに対する質問。

AIの応答

box_ask_ai_tool_multi_file

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

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

  • prompt (str): AIに対する指示。

AIが生成した回答

box_hubs_ask_ai_tool

HubについてBox AIに質問します

  • hubs_id (str): HubのID。

  • prompt (str): AIに対する質問。

AIの応答

box_ai_extract_data

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

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

  • fields (str): 抽出するフィールド。

JSON形式で抽出されたデータ

Box Doc Genのツール

ツール

説明

パラメータ

戻り値

box_docgen_create_batch_tool

テンプレートを使用してドキュメントを生成します

  • file_id (str): テンプレートファイルID。
  • destination_folder_id (str): 出力フォルダID。
  • user_input_file_path (str): JSON入力データのパス。
  • output_type (str, optional): 出力形式。

一括生成の結果

box_docgen_get_job_tool

IDを指定してDoc Genジョブを取得します

job_id (str): ジョブの識別子

JSON形式のジョブの詳細

box_docgen_list_jobs_tool

すべてのDoc Genジョブのリストを取得します

  • marker (str, optional): ページ割りのマーカー。
  • limit (int, optional): 返される最大ジョブ数。

JSON形式のジョブのリスト

box_docgen_list_jobs_by_batch_tool

特定のバッチ内にあるジョブのリストを取得します

  • batch_id (str): バッチの識別子。
  • marker (str, optional): ページ割りのマーカー。
  • limit (int, optional): 返される最大ジョブ数。

バッチジョブの詳細

box_docgen_template_create_tool

ファイルをテンプレートとして設定します

file_id (str): 設定するファイルID

テープレートの詳細

box_docgen_template_list_tool

すべての使用可能なテンプレートのリストを取得します

  • marker (str, optional): ページ割りのマーカー。
  • limit (int, optional): リストに取得するテンプレートの最大数。

テンプレートのリスト

box_docgen_template_delete_tool

テンプレートの設定を削除します

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

削除の確認

box_docgen_template_get_by_id_tool

テンプレートの詳細を取得します

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

テープレートの詳細

box_docgen_template_list_tags_tool

テンプレートタグのリストを取得します

  • template_id (str): テンプレートID。
  • template_version_id (str, optional): バージョンID。
  • marker (str, optional): ページ割りのマーカー。
  • limit (int, optional): 返される最大タグ数。

タグのリスト

box_docgen_template_list_jobs_tool

テンプレートを使用してジョブのリストを取得します

  • template_id (str): テンプレートの識別子。
  • marker (str, optional): ページ割りのマーカー。
  • limit (int, optional): リストに取得する最大ジョブ数。

ジョブの詳細

Boxメタデータのツール

ツール

説明

パラメータ

戻り値

box_metadata_template_get_by_key_tool

キーを指定してメタデータテンプレートを取得します。

template_name (str): 取得するメタデータテンプレートのキー。

指定したキーに関連付けられているメタデータテンプレート。

box_metadata_template_get_by_name_tool

名前を指定してメタデータテンプレートを取得します。

template_name (str): 取得するメタデータテンプレートの名前。

指定した名前に関連付けられているメタデータテンプレート。

トラブルシューティング

Claude for DesktopでMCPサーバーを実行したときにmacOSでError: spawn uv ENOENTが発生した場合は、以下を実行できます。

  • Homebrewを使用してuvを削除し手再インストールする: brew install uv
  • 構成内にuv実行可能ファイルのフルパスを指定する
/Users/USER_NAME/.local/bin/uv --directory /Users/USER_NAME/local/mcp-server-box run src/mcp_server_box.py

設定に関連するその他の問題が発生した場合は、BoxのDeveloper Communityフォーラムに質問を投稿してください (英語のみ)。