MCP Server Colab Exec

🚀 mcp-server-colab-exec

Google ColabのGPUランタイム（T4/L4）を割り当て、その上でPythonコードを実行するMCPサーバーです。Claude Code、Claude Desktop、Gemini CLI、ClineなどのMCP互換AIアシスタントが、ローカルのGPUハードウェアなしでGPUアクセラレーションされたコード（CUDA、PyTorch、TensorFlow）を実行できるようにします。

🚀 クイックスタート

このサーバーを使うことで、AIアシスタントがGoogle ColabのGPUを利用してPythonコードを実行できます。以下の前提条件を満たし、インストールと設定を行ってください。

✨ 主な機能

• Google ColabのGPUランタイム（T4/L4）を割り当て、Pythonコードを実行する。
• MCP互換のAIアシスタントがローカルのGPUハードウェアなしでGPUアクセラレーションされたコードを実行できる。

📦 インストール

pip install mcp-server-colab-exec

または、uvxを使って直接実行することもできます。

uvx mcp-server-colab-exec

📚 ドキュメント

前提条件

• Python 3.10以上
• Google ColabにアクセスできるGoogleアカウント
• 初回実行時には、OAuth2の同意を求めるブラウザウィンドウが開きます。トークンは~/.config/colab-exec/token.jsonにキャッシュされ、以降の実行では再利用されます。

設定

Claude Code

プロジェクトの.mcp.jsonまたは~/.claude/.mcp.jsonに以下を追加します。

{
  "mcpServers": {
    "colab-exec": {
      "command": "mcp-server-colab-exec"
    }
  }
}

または、CLIを使って以下のコマンドを実行します。

claude mcp add colab-exec mcp-server-colab-exec

Claude Desktop

claude_desktop_config.jsonに以下を追加します。

{
  "mcpServers": {
    "colab-exec": {
      "command": "mcp-server-colab-exec"
    }
  }
}

Gemini CLI

gemini mcp add colab-exec -- mcp-server-colab-exec

ツール

colab_execute

ColabのGPUランタイム上でインラインのPythonコードを実行します。

各セルの出力、エラー、およびstderrを含むJSONを返します。

colab_execute_file

ColabのGPUランタイム上でローカルの.pyファイルを実行します。

セキュリティポリシー: file_pathは現在のワークスペース（cwd）内の.pyファイルでなければなりません。

colab_execute_notebook

コードを実行し、生成されたすべてのアーティファクト（画像、CSV、モデルなど）を収集します。

アーティファクトはzip形式でダウンロードされ、output_dirに展開されます。展開前にzipメンバーが検証され、パストラバーサルや特殊ファイルの書き込みを防止します。

認証

初回使用時には、サーバーがGoogle OAuth2の同意を求めるブラウザウィンドウを開きます。アクセストークンとリフレッシュトークンは~/.config/colab-exec/token.jsonにキャッシュされます。以降の実行ではキャッシュされたトークンが使用され、自動的に更新されます。

OAuth2のクライアント資格情報は、公式のGoogle Colab VS Code拡張機能（google.colab@0.3.0）で使用されるものと同じです。これらは意図的に公開されています。

トラブルシューティング

• "GPU quota exceeded" — Colabには使用制限があります。しばらく待ってから再試行するか、別のGoogleアカウントを使用してください。
• "Timed out creating kernel session" — ランタイムの起動に時間がかかりすぎました。再試行してください — Colabはピーク時に遅延が発生することがあります。
• "Authentication failed" — ~/.config/colab-exec/token.jsonを削除し、再度認証してください。
• OAuthブラウザウィンドウが開かない — ブラウザが使用可能な環境で実行していることを確認してください。ヘッドレスサーバーの場合は、まずブラウザがあるマシンで認証し、トークンファイルをコピーしてください。

💻 使用例

基本的な使用法

GPUの利用可能性を確認する:

colab_execute(code="import torch; print(torch.cuda.is_available()); print(torch.cuda.get_device_name(0))")

nvidia-smiを実行する:

colab_execute(code="import subprocess; print(subprocess.run(['nvidia-smi'], capture_output=True, text=True).stdout)")

高度な使用法

モデルを訓練し、重みをダウンロードする:

colab_execute_notebook(
    code="import torch; model = torch.nn.Linear(10, 1); torch.save(model.state_dict(), '/tmp/model.pt')",
    output_dir="./outputs"
)

📄 ライセンス

MIT