メインコンテンツへスキップ
セルフホスト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がマシンにインストールされていない場合はインストールします。
curl -LsSf https://astral.sh/uv/install.sh | sh
その後ターミナルを再起動し、uvコマンドが取得されることを確認します。
  1. プロジェクトを作成して設定します。
# Create virtual environment and activate it
uv venv
source .venv/bin/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を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デスクトップアプリを再起動します。
  2. box_authorize_app_toolを使用してBox MCPサーバーを認証します。

​
利用可能なツール

​
認証と承認

ツール説明パラメータ戻り値
get_box_clientコンテキストからBoxクライアントを取得するためのヘルパー関数
  • ctx (Context): リクエストのコンテキスト。
Boxクライアントインスタンス
box_who_am_i現在のユーザーの情報を取得します
  • ctx (Context): リクエストのコンテキスト。
ユーザー情報の文字列
box_authorize_app_toolBoxアプリケーションを承認しますなし承認ステータスメッセージ

​
検索とナビゲーション

ツール説明パラメータ戻り値
box_search_toolBox内のファイルを検索します
  • 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_toolBoxファイルのテキストコンテンツを読み取ります
  • 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_toolBoxからファイルをダウンロードします
  • file_id (str): ファイルID。
  • save_file (bool, optional): ローカルに保存するかどうか。
  • save_path (str, optional): ローカルの保存パス。
ファイルコンテンツまたは保存の確認
get_file_contentファイルからテキストコンテンツを抽出します
  • file_id (str): ファイルID。
テキストのファイルコンテンツ

​
フォルダ管理

ツール説明パラメータ戻り値
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_toolHubについてBox AIに質問します
  • hubs_id (str): HubのID。
  • prompt (str): AIに対する質問。
AIの応答
box_ai_extract_dataAIを使用してファイルからデータを抽出します
  • file_id (str): ファイルID。
  • fields (str): 抽出するフィールド。
JSON形式で抽出されたデータ

​
コラボレーション

ツール説明パラメータ戻り値
box_collaboration_list_by_file_tool特定のファイルのすべてのコラボレーションのリストを取得します
  • ctx (Context): リクエストのコンテキスト。
  • file_id (str): BoxファイルのID。
コラボレーションのリスト (JSON形式)
box_collaboration_list_by_folder_tool特定のフォルダのすべてのコラボレーションのリストを取得します
  • ctx (Context): リクエストのコンテキスト。
  • folder_id (str): BoxフォルダのID。
コラボレーションのリスト (JSON形式)
box_collaboration_delete_tool特定のコラボレーションを削除します
  • ctx (Context): リクエストのコンテキスト。
  • collaboration_id (str): コラボレーションのID。
削除の確認
box_collaboration_file_group_by_group_id_toolグループをコラボレータとしてファイルに追加します
  • ctx (Context): リクエストのコンテキスト。
  • file_id (str): BoxファイルのID。
  • group_id (str): グループのID。
  • role (str, optional): コラボレーションロール (デフォルト: 「編集者」)。
作成されたコラボレーションの詳細

​
グループ

ツール説明パラメータ戻り値
box_groups_search_tool名前でグループを検索します (部分一致)
  • ctx (Context): リクエストのコンテキスト。
  • query (str): 検索クエリ。
一致するグループのリスト (JSON形式)
box_groups_list_members_tool特定のグループのすべてのメンバーのリストを取得します
  • ctx (Context): リクエストのコンテキスト。
  • group_id (str): グループのID。
グループメンバーのリスト (JSON形式)
box_groups_list_by_user_tool特定のユーザーが属しているすべてのグループを取得します
  • ctx (Context): リクエストのコンテキスト。
  • user_id (str): ユーザーのID。
グループのリスト (JSON形式)

​
ユーザー

ツール説明パラメータ戻り値
box_users_list_toolBoxアカウント内のすべてのユーザーのリストを取得します
  • ctx (Context): リクエストのコンテキスト。
ユーザーのリスト (JSON形式)
box_users_locate_by_name_tool名前でユーザーを検索します (完全一致)
  • ctx (Context): リクエストのコンテキスト。
  • name (str): ユーザーの名前。
ユーザーの詳細 (JSON形式)
box_users_locate_by_email_toolメールアドレスでユーザーを検索します (完全一致)
  • ctx (Context): リクエストのコンテキスト。
  • email (str): メールアドレス。
ユーザーの詳細 (JSON形式)
box_users_search_by_name_or_email_tool名前またはメールアドレスでユーザーを検索します (部分一致)
  • ctx (Context): リクエストのコンテキスト。
  • query (str): 検索クエリ。
一致するユーザーのリスト (JSON形式)

​
Boxの共有リンク

ツール説明パラメータ戻り値
box_shared_link_file_get_toolファイルの共有リンクを取得します
  • ctx (Context): リクエストのコンテキスト。
  • file_id (str): ファイルのID。
共有リンクの詳細 (JSON形式)
box_shared_link_file_create_or_update_toolファイルの共有リンクを作成または更新します
  • ctx (Context): リクエストのコンテキスト。
  • file_id (str): ファイルのID。
  • access (str, optional): アクセスレベル。
  • can_download (bool, optional): ダウンロード可能かどうか。
  • can_preview (bool, optional): プレビュー可能かどうか。
  • can_edit (bool, optional): 編集可能かどうか。
  • password (str, optional): パスワード。
  • vanity_name (str, optional): バニティ名。
  • unshared_at (str, optional): 有効期限。
作成/更新された共有リンクの詳細 (JSON形式)

​
Box Toolsのウェブリンク

ツール説明パラメータ戻り値
box_web_link_create_toolBoxウェブリンクを作成します
  • ctx (Context): リクエストのコンテキスト。
  • url (str): ウェブリンクのURL。
  • parent_folder_id (str): 親フォルダID。
  • name (str, optional): ウェブリンクの名前。
  • description (str, optional): 説明。
作成されたウェブリンクの詳細 (JSON形式)
box_web_link_get_by_id_toolIDを指定してBoxウェブリンクを取得します
  • ctx (Context): リクエストのコンテキスト。
  • web_link_id (str): ウェブリンクのID。
ウェブリンクの詳細 (JSON形式)
box_web_link_update_by_id_toolIDを指定してBoxウェブリンクを更新します
  • ctx (Context): リクエストのコンテキスト。
  • web_link_id (str): ウェブリンクのID。
  • url (str): 新しいURL。
更新されたウェブリンクの詳細 (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_toolIDを指定して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): 取得するメタデータテンプレートの名前。指定した名前に関連付けられているメタデータテンプレート。
box_metadata_template_create_toolメタデータテンプレートを作成します。
  • ctx (Context): コンテキストオブジェクト
  • display_name (str): メタデータテンプレートの表示名
  • fields (List[Dict[str, Any]]): フィールド定義のリスト (型、キー、表示名、説明、非表示、オプション (列挙/複数選択用) を含む)
  • template_key (Optional[str]): メタデータテンプレートのキー (省略可)
作成されたメタデータテンプレート。
box_metadata_set_instance_on_file_toolファイルにメタデータインスタンスを設定します。
  • ctx (Context): コンテキストオブジェクト
  • template_key (str): メタデータテンプレートのキー
  • file_id (str): メタデータを設定するファイルのID
  • metadata (dict): 設定するメタデータ値
ファイルに関連付けられているメタデータインスタンス。
box_metadata_update_instance_on_file_toolファイルのメタデータインスタンスを更新します。
  • ctx (Context): コンテキストオブジェクト
  • file_id (str): メタデータを更新するファイルのID
  • template_key (str): メタデータテンプレートのキー
  • metadata (dict): 更新するメタデータ値
  • remove_non_included_data (bool): Trueの場合、メタデータに含まれていないフィールドを削除
メタデータ更新後のBox APIからのレスポンス。
box_metadata_delete_instance_on_file_toolファイルのメタデータインスタンスを削除します。
  • ctx (Context): コンテキストオブジェクト
  • file_id (str): メタデータを削除するファイルのID
  • template_key (str): メタデータテンプレートのキー
メタデータ削除後のBox APIからのレスポンス。

​
トラブルシューティング

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フォーラムに質問を投稿してください (英語のみ)。