Execute Python code on a Google Colab GPU/TPU runtime.

Primary tool for running GPU/TPU-accelerated Python code (ML training, inference, CUDA operations). Allocates hardware, runs the code, and returns structured JSON with per-cell output, errors, and stderr.

After execution:

• If background=True, poll with colab_poll(job_id) for results.

• If OOM error occurs, reduce batch_size or upgrade to A100/H100.

• If import error, add pip install <pkg> before your main code.

• To persist outputs to Google Drive, use the drive_save parameter.

• To pre-load data from Drive, use the drive_fetch parameter.

Common issues:

• QUOTA_EXCEEDED: Colab rate limit hit. Wait a few minutes or switch to a different accelerator type.

• CUDA_ERROR: Driver mismatch or GPU init failure. Retry, or try T4.

• Only ONE background job can run at a time (Colab limitation).

Args: code: Python code to execute on the Colab runtime. accelerator: Hardware accelerator type. Default: "T4". GPU types: "T4" - NVIDIA Tesla T4 (16 GB, free-tier) "L4" - NVIDIA L4 (24 GB, Colab Pro) "A100" - NVIDIA A100 (40 GB, Colab Pro/Pro+) "H100" - NVIDIA H100 (80 GB, Colab Pro+) "G4" - NVIDIA G4 (Colab Pro+) TPU types: "V5E1" - TPU v5e-1 (Colab Pro+) "V6E1" - TPU v6e-1 (Colab Pro+) high_memory: Enable high-memory runtime (more RAM). Default: False. timeout: Max execution time in seconds (10-3600). Default: 300. background: Run in background (non-blocking). Default: False. When True, returns immediately with a job_id that can be polled via colab_poll. Incompatible with drive_fetch/drive_save. drive_fetch: JSON mapping Drive paths to Colab paths. Files are downloaded from Google Drive BEFORE your code runs. Example: '{"colab_data/train.csv": "/content/train.csv"}' Requires prior colab_drive_upload to place files on Drive. drive_save: JSON mapping Colab paths to Drive paths. Files are uploaded to Google Drive AFTER your code finishes, using a freshly obtained token (safe for long-running tasks). Example: '{"/content/model.pt": "results/model.pt"}'

Execute a local Python file on a Google Colab GPU/TPU runtime.

Reads the file contents and sends them for execution on a Colab runtime. Use this instead of colab_execute when you already have a .py script file ready to run.

After execution:

• Check exit_code and cell outputs in the response.

• If you need to collect output files (models, images), use colab_execute_notebook instead.

Common issues:

• Only .py files are accepted (security restriction).

• File must exist at the given path on the local machine.

Args: file_path: Path to a local .py file to execute on Colab. accelerator: Hardware accelerator type. Default: "T4". GPU types: "T4" - NVIDIA Tesla T4 (16 GB, free-tier) "L4" - NVIDIA L4 (24 GB, Colab Pro) "A100" - NVIDIA A100 (40 GB, Colab Pro/Pro+) "H100" - NVIDIA H100 (80 GB, Colab Pro+) "G4" - NVIDIA G4 (Colab Pro+) TPU types: "V5E1" - TPU v5e-1 (Colab Pro+) "V6E1" - TPU v6e-1 (Colab Pro+) high_memory: Enable high-memory runtime (more RAM). Default: False. timeout: Max execution time in seconds (10-3600). Default: 300.

Execute Python code on Colab GPU/TPU and collect generated artifacts.

Runs the code, then scans the runtime for output files (images, CSVs, models, etc.), zips them, and downloads to a local directory. Use this when your code produces files you need to retrieve locally.

After execution:

• Check artifact_files in the response for collected output filenames.

• Files are extracted to the specified output_dir.

• For files larger than 50 MB, use colab_execute with drive_save instead.

Common issues:

• No artifacts collected: ensure your code writes files to /tmp, /content, or the current working directory.

• Each artifact file must be under 50 MB (base64 transfer limit).

Args: code: Python code to execute on the Colab runtime. output_dir: Local directory to save the artifacts zip and extracted files. accelerator: Hardware accelerator type. Default: "T4". GPU types: "T4" - NVIDIA Tesla T4 (16 GB, free-tier) "L4" - NVIDIA L4 (24 GB, Colab Pro) "A100" - NVIDIA A100 (40 GB, Colab Pro/Pro+) "H100" - NVIDIA H100 (80 GB, Colab Pro+) "G4" - NVIDIA G4 (Colab Pro+) TPU types: "V5E1" - TPU v5e-1 (Colab Pro+) "V6E1" - TPU v6e-1 (Colab Pro+) high_memory: Enable high-memory runtime (more RAM). Default: False. timeout: Max execution time in seconds (10-3600). Default: 300.

Cancel an active background job.

Marks the job as cancelled and attempts to cancel the underlying asyncio task. Use colab_jobs to find active job IDs.

After cancellation:

• Verify with colab_poll(job_id) that the status is 'cancelled'.

• The Colab runtime is released automatically.

• You can then start a new background job with colab_execute.

Common issues:

• Cannot cancel a job that is already completed, failed, or cancelled.

• Use colab_jobs first if you don't have the job_id.

Args: job_id: The job identifier returned by colab_execute.

Poll a background job for its current status and results.

Use this after launching a background execution with colab_execute(..., background=True) to check progress and retrieve results when complete.

Interpreting the response:

• status='starting' or 'running': job is in progress, poll again later.

• status='completed': result field contains the execution output.

• status='failed': error field describes what went wrong.

• status='cancelled': job was stopped via colab_cancel.

Common issues:

• Unknown job_id: use colab_jobs to list all tracked jobs.

• Jobs are cleaned up automatically after 5 minutes.

Args: job_id: The job identifier returned by colab_execute.

List all tracked background jobs.

Returns a JSON array of job summaries including job_id, status, accelerator type, and timestamps. Use this to find job IDs for colab_poll or colab_cancel.

After listing:

• Use colab_poll(job_id) on any job to get detailed results.

• Use colab_cancel(job_id) to stop an active job.

• Completed/failed/cancelled jobs are auto-cleaned after 5 minutes.

Upload a local file to Google Drive.

Use this to stage input data before running colab_execute with the drive_fetch parameter. The file is uploaded to the specified folder under MyDrive.

After upload:

• Pass the drive path in colab_execute's drive_fetch parameter to make the file available on the Colab runtime.

• Example: colab_execute(code="...", drive_fetch='{"colab_data/train.csv": "/content/train.csv"}')

Common issues:

• First use requires Google Drive OAuth authorization (browser popup).

• Nested folders (e.g. 'data/train') are created automatically.

Args: local_path: Path to the local file to upload. drive_folder: Target folder path on Google Drive (relative to MyDrive). Nested paths like 'data/train' are supported. Folders are created automatically if they don't exist. Default: "colab_data".

Download a file from Google Drive to a local path.

Use this to retrieve results saved to Drive by colab_execute with the drive_save parameter, or any file stored on Google Drive.

After download:

• The file is saved at the specified local_path.

• Process or inspect the file locally as needed.

Common issues:

• File not found: verify the drive_path matches the Drive folder structure (relative to MyDrive root).

• First use requires Google Drive OAuth authorization.

Args: drive_path: File path on Google Drive relative to MyDrive (e.g. 'results/model.pt' or 'colab_data/output.csv'). local_path: Local destination path where the file will be saved.

Return current server status including accelerator info and job state.

Use this before executing code to check which accelerators are available and whether a background job is already running (only one background job is allowed at a time).

After checking status:

• Choose an accelerator from supported_accelerators for colab_execute.

• If active_job is present, wait for it or cancel with colab_cancel before starting a new background job.

Return the mcp-colab-gpu server version.

Use this to verify server compatibility or for debugging.