Colab Drive MCP

Colab Drive MCP

Google Drive を通じて、Google Colab 互換の .ipynb ノートブックを安全に 確認、編集、同期するための MCP サーバーです。

重要

これはノートブックファイルの同期サーバーであり、ノートブック実行 サービスではありません。 Google Drive を通じて .ipynb ファイルを転送、編集します。 Colab ランタイムへの接続、セルの実行、Run all のクリック、 セッションの維持、Colab ブラウザー UI の自動操作、Colab の制限の回避は行いません。

AI エージェントがノートブックをローカルで準備し、Drive と同期して、 実行済みの出力を確認したり、編集したノートブックをユーザーに返したりする必要がある場合に、この MCP を使用してください。 同期したノートブックは、Colab、Jupyter、 VS Code、または別のノートブックランタイムで、別途開いて実行してください。

機能

• ノートブック全体を読み込まずに、セルを確認、編集できます。
• ノートブックの作成、検索、コピー、アップロード、ダウンロードができます。
• 進行状況を要求する MCP クライアントに、アップロードとダウンロードの進行状況をリアルタイムで通知します。
• Drive のメタデータとコンテンツの MD5 を使用して、ローカルと Drive のノートブックを比較します。
• ローカルファイルへのアクセスを、設定したルートディレクトリ内に制限します。
• ダウンロード時に、Colab 固有のストリーム出力メタデータを正規化します。
• 予期せずブラウザーを開かずに、Google Drive の設定を診断します。
• 認証情報の不足、認証の期限切れ、権限、ファイルの不足、レート制限について、対処可能なエラーを返します。

対象外

• Google Colab ランタイムの起動、制御、監視。
• Colab ランタイムが接続中、ビジー状態、またはファイルを実行中かどうかの検出。
• ノートブックのセルのローカルまたはリモートでの実行。
• ブラウザーの自動操作、自動的な Run all、または無人の Colab セッション。
• Colab の割り当て、アイドルタイムアウト、アクセス制御、利用ポリシーの回避。
• ノートブックに含まれるプロジェクトのデプロイや実行。

AI 向け契約

MCP の初期化応答には、このプロジェクトをファイル同期専用として定義する、サーバー全体に適用される指示が含まれています。 ツールの説明でも、必要な箇所で同じ境界を繰り返し示します。

manifest.0 には、エージェントとリポジトリツール向けの型付き Zero 言語契約として、同じ目的、機能、対象外事項が記載されています。

ツール

セットアップ

• get_google_drive_status：依存関係、認証情報、トークン、スコープを診断します。
• authorize_google_drive：Google OAuth のブラウザーフローを明示的に開きます。

ローカルのノートブック

• list_local_notebooks、get_local_notebook、create_local_notebook
• add_local_cell、update_local_cell、delete_local_cell
• search_local_cells、clear_local_outputs

Google Drive

• list_drive_notebooks、pull_drive_notebook、push_local_notebook
• get_notebook_sync_status、copy_drive_notebook、get_colab_url

pull_drive_notebook と push_local_notebook は、ノートブックファイルを同期します。 クライアントが進行状況トークンを指定すると、MCP の進行状況通知を送信しますが、 通知を表示するかどうか、および表示方法はクライアントが決定します。ノートブックのコードは実行しません。 get_colab_url は URL を返しますが、ブラウザーは開きません。

get_notebook_sync_status は、ローカルノートブックのアップロード時の表現を Drive の MD5 チェックサムと比較し、in_sync、differs、remote_only、または unknown を返します。 また、更新日時やバージョンなどの Drive メタデータも返します。 Google Drive では Colab ランタイムのアクティビティが公開されていないため、Colab が現在ノートブックを実行中かどうかは判定できません。

インストール

uvx を使って PyPI から直接実行します：

COLAB_MCP_ROOT="$HOME/notebooks" uvx --from 'colab-drive-mcp[drive]' colab-drive-mcp

または、ソースからインストールします：

git clone https://github.com/YummyTastyCode/colab-drive-mcp.git
cd colab-drive-mcp
python3 -m venv .venv
.venv/bin/pip install -e '.[drive]'

サーバーを実行します：

COLAB_MCP_ROOT="$HOME/notebooks" .venv/bin/colab-drive-mcp

ローカルツールからアクセスできるのは、COLAB_MCP_ROOT 以下の .ipynb ファイルのみです。

このサーバーは、公式 MCP Registry に次のとおり公開されています：

io.github.YummyTastyCode/colab-drive-mcp

Google Drive の設定

最初に get_google_drive_status を呼び出します。ブラウザーを開いたり、ファイルを変更したりすることはありません。応答には、次に必要な手順が示されます。

Drive を有効にするには：

1. Google Cloud プロジェクトを作成します。
2. Google Drive API を有効にします。
3. OAuth 同意画面を設定し、テストユーザーとして自分のアカウントを追加します。
4. アプリケーションの種類を デスクトップアプリ にして OAuth クライアント ID を作成します。
5. JSON を ~/.config/colab-mcp/credentials.json にダウンロードします。
6. authorize_google_drive を呼び出し、Google のサインインフローを完了します。

生成されたトークンは ~/.config/colab-mcp/token.json に保存されます。

次の環境変数で保存場所を変更できます：

• COLAB_MCP_GOOGLE_CREDENTIALS
• COLAB_MCP_GOOGLE_TOKEN

OAuth 認証情報やトークンをコミットしないでください。

Drive のアクセスモード

デフォルトのモードは file で、Google のより限定的な drive.file スコープを使用します：

COLAB_MCP_DRIVE_ACCESS=file

このモードでは、この OAuth アプリで作成したファイル、または明示的に開いたファイルにアクセスできます。ユーザーの Drive にある既存のすべてのノートブックを確実に一覧表示することはできません。

既存の Drive ノートブックを検索して更新するには、フルアクセスを明示的に有効にします：

COLAB_MCP_DRIVE_ACCESS=full

アクセスモードを変更するには、token.json を削除して authorize_google_drive を再度呼び出す必要がある場合があります。

Codex の設定

codex mcp add colab-drive \
  --env COLAB_MCP_ROOT="$HOME/notebooks" \
  --env COLAB_MCP_DRIVE_ACCESS=file \
  -- /absolute/path/to/colab-drive-mcp/.venv/bin/colab-drive-mcp

VS Code の設定

このサーバーを VS Code の MCP 設定に追加します：

{
  "servers": {
    "colab-drive": {
      "type": "stdio",
      "command": "/absolute/path/to/colab-drive-mcp/.venv/bin/colab-drive-mcp",
      "env": {
        "COLAB_MCP_ROOT": "/absolute/path/to/notebooks",
        "COLAB_MCP_DRIVE_ACCESS": "file"
      }
    }
  }
}

Colab との互換性

Google Colab は、ストリーム出力に metadata プロパティを追加する場合があります。このプロパティは標準の nbformat v4 スキーマでは無効です。Drive からのダウンロード時に、このサーバーは互換性のないプロパティのみを削除します。ストリームのテキストとその他すべての出力は保持されます。

セキュリティ

• OAuth トークンはローカルマシンに保存されます。
• ローカルツールのアクセス先は COLAB_MCP_ROOT に限定されます。
• 認証には、明示的な authorize_google_drive の呼び出しが必要です。
• Drive 全体の検索が必要な場合を除き、file アクセスを使用してください。
• 既存の Drive ファイルを上書きする前に、操作内容を確認してください。

このプロジェクトは Google と提携しておらず、Google の推奨を受けたものでもありません。

開発

.venv/bin/pip install -e '.[drive,test]'
.venv/bin/pytest