セルフホスト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サーバーを設定するには、このセクションの手順に従います。

リポジトリを複製します。

git clone https://github.com/box-community/mcp-server-box.git
cd mcp-server-box

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コマンドが取得されることを確認します。

プロジェクトを作成して設定します。

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

ルートディレクトリに.envファイルを作成し、Box Platformアプリの資格情報を入力します。

BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret

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

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

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

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

前提条件:

Cursorデスクトップアプリをダウンロードする

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

Cursorアプリを開きます。
歯車アイコンをクリックして設定を開きます。
[Cursor Settings] タブで [MCP] を選択します。
[Add new global MCP server] ボタンをクリックします。これにより、mcp.jsonファイルが開きます。
ローカルの設定を使用して値を更新し、次のJSONを貼り付けます。

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

mcp.jsonファイルを保存して閉じます。
必要に応じて、Cursorを再起動します。
box_authorize_app_toolツールを使用して、Box MCPの使用を開始します。

前提条件:

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

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

claude_desktop_config.jsonを編集します。

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

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

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

構成を追加します。

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

Claudeデスクトップアプリを再起動します。
box_authorize_app_toolを使用してBox MCPサーバーを認証します。

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

ツール	説明	パラメータ	戻り値
`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)`: ローカルの保存パス。	ファイルコンテンツまたは保存の確認
`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_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_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_tool`	Boxアカウント内のすべてのユーザーのリストを取得します	`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_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_web_link_create_tool`	Boxウェブリンクを作成します	`ctx (Context)`: リクエストのコンテキスト。 `url (str)`: ウェブリンクのURL。 `parent_folder_id (str)`: 親フォルダID。 `name (str, optional)`: ウェブリンクの名前。 `description (str, optional)`: 説明。	作成されたウェブリンクの詳細 (JSON形式)
`box_web_link_get_by_id_tool`	IDを指定してBoxウェブリンクを取得します	`ctx (Context)`: リクエストのコンテキスト。 `web_link_id (str)`: ウェブリンクのID。	ウェブリンクの詳細 (JSON形式)
`box_web_link_update_by_id_tool`	IDを指定してBoxウェブリンクを更新します	`ctx (Context)`: リクエストのコンテキスト。 `web_link_id (str)`: ウェブリンクのID。 `url (str)`: 新しいURL。	更新されたウェブリンクの詳細 (JSON形式)

ツール	説明	パラメータ	戻り値
`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_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フォーラムに質問を投稿してください (英語のみ)。

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

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

インストール

前提条件

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

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

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

利用可能なツール

認証と承認

検索とナビゲーション

ファイル操作

フォルダ管理

Box AI

コラボレーション

グループ

ユーザー

Boxの共有リンク

Box Toolsのウェブリンク

Box Doc Gen

Boxメタデータ

トラブルシューティング