Skip to main content
Glama

gpu-bridge

An MCP server that lets an AI coding assistant run machine-learning work on remote GPUs: Kaggle, Google Colab and Hugging Face.

The server runs on your computer. The assistant calls its tools to get a GPU machine, start training in the background, follow the logs and metrics, look at plots, and copy the results back before the machine is recycled.

 AI client  ───────►  gpu-bridge  ───────►  Kaggle GPU      free, started for you
 (Cursor, Copilot,  (your computer)       Colab GPU       free, one pasted line
  Gemini…)                             Hugging Face    paid, billed per minute

Requirements: macOS, Linux or Windows, and an MCP-capable AI client. The installer fetches everything else, including Python (through uv).

Contents

Related MCP server: mcp-server-kaggle-exec

Install

Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/mahi-chan/gpu-bridge/main/install.sh | sh

(wget -qO- <same address> | sh works if curl is missing.)

Windows, in PowerShell:

irm https://raw.githubusercontent.com/mahi-chan/gpu-bridge/main/install.ps1 | iex

Inside WSL use the Linux command; it registers AI clients installed inside WSL. For Windows apps such as Cursor on Windows, run the PowerShell command instead.

The installer:

  1. downloads gpu-bridge to ~/.gpu-bridge/app (installing uv first if needed),

  2. creates an isolated Python environment from the locked dependencies,

  3. registers the server with every supported AI client it finds,

  4. adds a gpu-bridge command to your PATH.

Run the same command again to update. Restart your AI client afterwards.

Supported AI clients

Claude Code, Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf, Cline, Gemini CLI and Codex CLI. For any other client that can launch a local MCP server, gpu-bridge install --print prints the entry to paste into its settings.

Choose where the work runs

You need one of these. Each has a one-time setup; after that the assistant does the rest. docs/CONNECTING.md has the full walkthrough.

Cost

One-time setup

Starting a session

Kaggle

Free, about 30 GPU-hours a week

gpu-bridge login kaggle

Automatic

Google Colab

Free

None

You run one pasted line in a Colab cell

Hugging Face

Paid per minute

gpu-bridge login huggingface

Automatic

Colab needs the pasted line because Google offers no API for starting a session. Kaggle and Hugging Face do, so gpu-bridge starts those itself.

gpu-bridge doctor reports what is ready and what is still missing.

Using it

Ask the assistant in plain language. Some examples:

Request

What happens

"Connect a Kaggle GPU."

Starts a Kaggle session and attaches to it.

"Join the Titanic competition, train a baseline and submit it."

Attaches the data, trains in the background, submits, reports the score.

"Train PPO on CartPole with seeds 0, 1 and 2 and plot the rewards."

Three background runs, then reward curves.

"Fine-tune SmolLM2 with LoRA on a T4 for at most an hour."

Rents one Hugging Face machine for the job; it stops when training ends.

"How is the run going?"

Status, latest metrics and the end of the log.

"Save the checkpoints."

Downloads them, or pushes them to a private Hugging Face repo.

"Stop everything."

Ends the session and anything still billing.

Behaviour worth knowing:

  • Long runs execute in the background on the remote machine, so they survive chat timeouts and dropped connections. A new chat can re-attach to them.

  • The same training script and the same status, log, metric and plot tools work on all three platforms.

  • Remote disks are temporary. Save checkpoints as you go, to your computer or to a private Hugging Face repo.

Training scripts

Any Python script can be launched as a run. Four names are available inside it without importing anything:

Name

Purpose

log_metric(step, **values)

Records numbers for the status, metrics and plot tools.

save_checkpoint_file(path)

Keeps a file or folder as a checkpoint.

GPU_BRIDGE_RUN_DIR

The run's working folder.

SEED

The run's seed, set by seed sweeps.

Examples:

The assistant can also fetch them with the example_script tool.

Tools

The server exposes 54 tools.

Group

Tools

Get a machine

kaggle_runtime_start, colab_runtime_start, connect_runtime, runtime_stop, runtime_status

Hugging Face machines

hf_hardware, hf_job_launch, hf_job_list, hf_job_cancel, hf_runtime_start, hf_runtime_connect, hf_runtime_stop

Run code and files

run_code, upload_file, download_file, fetch_image

Training runs

launch_training, get_run_status, get_logs, get_metrics, plot_metrics, stop_run, list_runs, save_checkpoint, restore_checkpoint

Notebooks

notebook_create, notebook_read, notebook_add_cell, notebook_edit_cell, notebook_delete_cell, notebook_run_cell

Reinforcement learning

rl_setup, rl_reward_curve, rl_record_rollout, rl_seed_sweep

Computer vision

cv_load_dataset, cv_training_curves, cv_show_predictions

Kaggle competitions

kaggle_search_datasets, kaggle_competition_files, kaggle_submit, kaggle_submissions, kaggle_leaderboard

Hugging Face Hub and Spaces

hf_whoami, hf_search, hf_upload, hf_download, hf_push_run, hf_space_status, hf_space_hardware, hf_space_pause, hf_space_restart

Help

setup_guide, example_script

Command line

gpu-bridge doctor               show what is set up and the next step for anything missing
gpu-bridge login kaggle         log in to Kaggle (once)
gpu-bridge login huggingface    log in to Hugging Face (once)
gpu-bridge clients              list supported AI clients and where they were found
gpu-bridge install              register with AI clients (--client NAME, repeatable; --print)
gpu-bridge uninstall            remove it from them
gpu-bridge serve --http         serve over local HTTP, for clients that connect by URL

gpu-bridge serve without options runs the server over stdio, which is what the registered clients use. With --http it listens on http://127.0.0.1:8765/mcp.

Configuration

Variable

Effect

GPU_BRIDGE_RENDEZVOUS_URL

Relay used by new sessions to announce themselves. Defaults to ntfy.sh; point it at your own ntfy server if you prefer. Set it in the AI client's environment.

GPU_BRIDGE_DIR

Installer only: where the app is installed. Default ~/.gpu-bridge/app.

GPU_BRIDGE_BIN

Installer only: where the gpu-bridge command is placed. Default ~/.local/bin.

GPU_BRIDGE_BRANCH

Installer only: branch to install. Default main.

Kaggle and Hugging Face credentials are not configured here. They stay with the official tools: ~/.kaggle/kaggle.json and the Hugging Face token store.

Costs

  • Kaggle and Colab are free. A Kaggle session started by gpu-bridge ends on request, after 30 idle minutes, or at its time limit (6 hours by default), so it does not use up your weekly GPU quota.

  • Hugging Face bills per minute until a machine ends. Every machine gets a time limit, the interactive one shuts itself down after 30 idle minutes, and hf_job_list shows anything still running. hf_hardware shows current prices.

Security and privacy

  • Logins stay with the official Kaggle and Hugging Face tools on your computer. gpu-bridge does not write tokens into an AI client's configuration.

  • Kaggle and Colab sessions are reached through a temporary public tunnel protected by a random one-time code known only to your computer and that session.

  • To find a new session without manual copying, the session posts its tunnel address to a relay. Only the address is sent, signed with the one-time code so it cannot be swapped; the code itself never goes through the relay.

  • When a tool needs your Hugging Face or Kaggle login on the remote machine (pushing checkpoints, downloading competition data), the credential is lent for that single command and not stored.

  • gpu-bridge serve --http has no password. Keep it on localhost; anyone who can reach it can rent machines on your Hugging Face account.

Troubleshooting

Symptom

What to do

The assistant has no gpu-bridge tools

Restart the AI client and check gpu-bridge clients.

"No Kaggle login found"

Run gpu-bridge login kaggle.

A Kaggle session "ended before connecting"

Verify your phone number on kaggle.com (required for GPU and internet), or check that the weekly GPU quota is not used up.

"Not connected yet" on Colab

Check that the pasted cell is still running and has printed connected.

"No Hugging Face token found"

Run gpu-bridge login huggingface.

Hugging Face error 402

Add credits or a payment method at huggingface.co/settings/billing.

A run disappeared

The machine was recycled. Save checkpoints as you go.

Development

git clone https://github.com/mahi-chan/gpu-bridge.git
cd gpu-bridge
uv sync
uv run pytest
uvx ruff check src tests
./install.sh        # register this checkout with your AI clients

The tests cover the installers, every tool against a local Jupyter server, and the Kaggle and Hugging Face calls against stubs. Sessions on the live services depend on your accounts and are not covered; please open an issue with the message you saw if something misbehaves there.

src/gpu_bridge/
  cli.py, installer.py     the gpu-bridge command and the client installer
  server.py                registers every tool group
  tools/                   the tools, one module per group
  connectors/              Jupyter, Kaggle, Hugging Face, pairing, local state
  remote/entrypoint.py     the program that runs on the remote machine
examples/                  training scripts
docs/CONNECTING.md         connecting each platform, step by step
tests/                     test suite

License

MIT, see LICENSE.

Available Tools

54 tools
colab_runtime_startA

Prepare a Google Colab session. Returns one line for the user to run in Colab.

Google does not let a program start a Colab session, so the user does two things: open a notebook and run the line. Nothing is copied back: when the line is running, call connect_runtime and the session is found automatically. Show the user the steps exactly as returned.

Inputs: no named parameters. Returns: result

connect_runtimeA

Connect to (or re-attach to) the runtime. Call it with no arguments in most cases.

With no arguments it does the right thing: it finds the Colab/Kaggle session just started with colab_runtime_start / kaggle_runtime_start (waiting up to wait_seconds for it), or re-attaches to the runtime used before. Safe to call in every new session. (For a machine rented with hf_runtime_start, call hf_runtime_connect instead.)

url, token: only for connecting by hand to a Jupyter server whose address and token you were given. hf_auth: with url/token, set True for a JupyterLab running in a Hugging Face Space (url "https://-.hf.space", token = the Space's JUPYTER_TOKEN).

Inputs: url, token, hf_auth, wait_seconds. Returns: result

cv_load_datasetA

Download a Kaggle dataset or competition onto the runtime and unzip it.

ref: "owner/dataset-slug" for datasets, or the competition slug for competitions. kind: "dataset" or "competition". Works when this computer is logged in to Kaggle (the login is used for this one download and is not kept on the runtime), or on a Kaggle machine. On a session from kaggle_runtime_start, prefer its competition / datasets arguments: the data is then already under /kaggle/input/.

Inputs: ref (required), dest, kind, unzip. Returns: result

cv_show_predictionsA

Run inference/visualization code on the runtime and show the saved image inline.

inference_code runs on the runtime and should save its visualization (predictions, bounding boxes, masks, Grad-CAM, a batch grid…) to the path in the injected variable OUT. Example last line: plt.savefig(OUT) or cv2.imwrite(OUT, canvas).

Inputs: inference_code (required), out.

cv_training_curvesC

Plot standard CV metrics for a run (loss / accuracy / mAP / IoU — auto-detected).

Inputs: run_name (required).

download_fileC

Download a file from the runtime to the local machine.

Inputs: local_path (required), remote_path (required). Returns: result

example_scriptA

Return a ready-made training script to pass to launch_training / hf_job_launch.

With no name it lists the examples (LLM LoRA fine-tune, RL PPO, CV CNN). Each script's header says how to launch it and which settings it accepts.

Inputs: name. Returns: result

fetch_imageA

Fetch an image file (png/jpg) from the runtime and show it inline.

Use for prediction visualizations, Grad-CAM, rollout frames, or any figure your code saved to disk on the runtime.

Inputs: remote_path (required).

get_logsB

Return the last tail lines of a run's stdout/stderr log.

Inputs: run_name (required), tail. Returns: result

get_metricsB

Return the last tail logged metric records (JSON lines) for a run.

Inputs: run_name (required), tail. Returns: result

get_run_statusB

Check whether a launched run is still alive and how many metric rows it has logged.

Inputs: run_name (required). Returns: result

hf_downloadB

Download one file (or, with no filename, a whole repo) from the Hub to the local machine.

Inputs: repo_id (required), local_dir (required), filename, repo_type. Returns: result

hf_hardwareA

List the machines Hugging Face rents for jobs, with specs and price per hour.

Inputs: no named parameters. Returns: result

hf_job_cancelA

Cancel any Hugging Face job by id (from hf_job_list), stopping its billing.

Inputs: job_id (required). Returns: result

hf_job_launchA

Run a training script on its own rented Hugging Face machine; returns immediately.

The machine is billed per minute and stops when the script ends, fails, or hits timeout — so set timeout generously for real trainings (e.g. "6h"). The script may use the injected helpers log_metric(step, **kv), save_checkpoint_file(path) (uploads a file or folder to the private Hub repo <you>/<run_name>) and SEED. Follow it with get_run_status / get_logs / get_metrics / plot_metrics, cancel with stop_run, fetch results with save_checkpoint.

flavor: machine type from hf_hardware, e.g. "t4-small", "a10g-small", "a100-large". timeout: time limit such as "30m", "2h", "1d". requirements: space-separated pip packages, e.g. "torch transformers peft datasets". env_json: JSON object of extra environment variables. image: optional Docker image that has uv installed (default: a plain Python image; pip-installed torch brings its own CUDA libraries).

Inputs: script (required), run_name (required), image, flavor, +3 more. Returns: result

hf_job_listB

List your Hugging Face jobs. By default only those running (and billing) right now.

Inputs: include_finished. Returns: result

hf_push_runA

Upload a run's folder (checkpoints, metrics, log, script) from the runtime to the Hub.

The upload goes straight from the remote machine, in the background, so large checkpoints never pass through this computer. Call it again to check progress. It uses this computer's Hugging Face login for that one upload; the token is not kept on the runtime.

repo_id: defaults to "/<run_name>".

Inputs: run_name (required), private, repo_id. Returns: result

hf_runtime_connectA

Attach to the Hugging Face runtime started with hf_runtime_start.

Safe to call repeatedly and in every new session: it reports progress while the machine is still starting, and re-attaches to the same kernel once it is up.

Inputs: wait_seconds. Returns: result

hf_runtime_startA

Rent a Hugging Face machine running Jupyter, to use like a Colab/Kaggle runtime.

Returns at once; then call hf_runtime_connect (the machine needs a minute or two). Billing runs per minute until hf_runtime_stop, the timeout, or idle_minutes with nothing running — whichever comes first. The disk is temporary: push results with hf_push_run or save_checkpoint before stopping.

flavor: machine type from hf_hardware, e.g. "t4-small", "a10g-small", "l4x1". timeout: hard time limit such as "2h" or "8h". idle_minutes: shut down after this long with no activity and no run in progress (0 disables the idle shutdown). image: Docker image with Python 3; defaults to an official PyTorch + CUDA image.

Inputs: image, flavor, timeout, idle_minutes. Returns: result

hf_runtime_stopA

Shut down the Hugging Face runtime and stop its billing.

Everything on its disk is lost: push results first (hf_push_run / save_checkpoint).

Inputs: no named parameters. Returns: result

hf_space_hardwareB

Change a Space's hardware (e.g. "t4-small", "a10g-small", or "cpu-basic" for free).

Paid hardware is billed per minute while the Space runs. sleep_minutes > 0 puts the Space to sleep after that long without visitors, which pauses the billing.

Inputs: hardware (required), space_id (required), sleep_minutes. Returns: result

hf_space_pauseB

Pause a Space: it stops running and stops billing until restarted.

Inputs: space_id (required). Returns: result

hf_space_restartB

Restart (or wake) a Space. On paid hardware, billing resumes.

Inputs: space_id (required). Returns: result

hf_space_statusA

Show a Space's state, hardware and URL. space_id is "/".

Inputs: space_id (required). Returns: result

hf_uploadB

Upload a local file or folder to a Hub repo (created if missing, private by default).

repo_id: "/". repo_type: "model", "dataset" or "space".

Inputs: repo_id (required), local_path (required), private, repo_type, +1 more. Returns: result

hf_whoamiA

Check the Hugging Face login: who the token belongs to and what it may do.

Inputs: no named parameters. Returns: result

kaggle_competition_filesC

List the downloadable files for a competition.

Inputs: competition (required). Returns: result

kaggle_leaderboardC

Show the top of a competition's public leaderboard.

Inputs: competition (required). Returns: result

kaggle_runtime_startA

Start a Kaggle GPU session without the browser, using the user's Kaggle login.

Returns at once; then call connect_runtime (Kaggle needs a minute or two). After that every runtime tool works on the Kaggle machine. It uses the account's free weekly GPU hours until runtime_stop, max_hours, or idle_minutes with nothing running.

competition: a competition slug to attach; its data appears under /kaggle/input/. (The user must have accepted the competition rules on kaggle.com.) datasets: comma-separated "owner/dataset" names to attach under /kaggle/input/. gpu: False starts a CPU session, which does not use GPU quota.

Inputs: gpu, datasets, max_hours, competition, +1 more. Returns: result

kaggle_search_datasetsA

Search Kaggle datasets by keyword (returns refs usable with cv_load_dataset).

Inputs: query (required). Returns: result

kaggle_submissionsB

List your recent submissions and their scores for a competition.

Inputs: competition (required). Returns: result

kaggle_submitB

Submit a file to a competition.

file: a path on this computer, or a path on the connected runtime (for example a run's submission.csv), which is fetched first.

Inputs: file (required), competition (required), message. Returns: result

launch_trainingA

Launch a training script as a background job on the runtime; returns immediately.

The script may call the injected helpers log_metric(step, **kv) and save_checkpoint_file(path), and read SEED. Poll with get_run_status / get_logs / get_metrics; plot with plot_metrics.

requirements: space-separated pip packages to install first (e.g. "stable-baselines3 gymnasium"). env_json: JSON object of extra environment variables for the run.

Inputs: script (required), run_name (required), env_json, requirements. Returns: result

list_runsA

List all training runs this MCP has launched (from the local registry).

The status shown is the last one seen; get_run_status checks a run live.

Inputs: no named parameters. Returns: result

notebook_add_cellB

Add a cell to a notebook. index=-1 appends; otherwise inserts before that index.

Inputs: path (required), source (required), index, cell_type. Returns: result

notebook_createC

Create a new empty notebook at path on the runtime.

Inputs: path (required). Returns: result

notebook_delete_cellC

Delete cell index from a notebook.

Inputs: path (required), index (required). Returns: result

notebook_edit_cellC

Replace the source of cell index in a notebook.

Inputs: path (required), index (required), source (required). Returns: result

notebook_readA

Read a notebook and list its cells with indices, types, and source previews.

Inputs: path (required). Returns: result

notebook_run_cellB

Execute a notebook cell's code on the kernel; optionally write outputs back.

Returns stdout/results and any images. Only 'code' cells are executed.

Inputs: path (required), index (required), timeout, write_output.

plot_metricsB

Plot one or more metric series for a run and return the chart as an image.

keys: comma-separated metric names, e.g. "loss,val_acc" or "reward".

Inputs: keys (required), run_name (required).

restore_checkpointB

Upload a locally-saved checkpoint file back into a run's checkpoints/ dir on the runtime.

Inputs: run_name (required), local_filename (required). Returns: result

rl_record_rolloutA

Render an episode and return a contact sheet of frames (and save a gif on the runtime).

rollout_code runs on the runtime and MUST leave a variable frames — a list of HxWx3 uint8 arrays (e.g. from env.render() with render_mode='rgb_array'). A rollout.gif is written to the run dir; download it with download_file.

Inputs: run_name (required), rollout_code (required), max_frames.

rl_reward_curveB

Plot the reward curve for an RL run (auto-detects reward-like metric keys).

Inputs: run_name (required).

rl_seed_sweepA

Launch the same training script across several seeds as separate runs.

seeds: comma-separated, e.g. "0,1,2". Each becomes a run '<run_name>_s' with GPU_BRIDGE_SEED set (read it as SEED in your script). Poll each run by name. hf_flavor: leave empty to run all seeds on the connected runtime. Set a Hugging Face machine type (e.g. "t4-small") to give every seed its own rented job, so they train in parallel; each is billed separately, up to hf_timeout.

Inputs: seeds (required), script (required), run_name (required), hf_flavor, +2 more. Returns: result

rl_setupA

Install a standard RL stack on the runtime (Gymnasium + Stable-Baselines3 + imageio).

extras: Gymnasium extras to include, e.g. "classic-control", "box2d", "atari,accept-rom-license". Also installs xvfb + pyvirtualdisplay for headless rendering.

Inputs: extras. Returns: result

run_codeA

Execute Python on the runtime; returns stdout/results plus any PNG images.

For quick, interactive work. Do NOT run long training here — it will hit the timeout. Use launch_training for anything that takes minutes.

Inputs: code (required), timeout.

runtime_statusA

Report kernel liveness, Python/CUDA info, GPU, RAM and disk on the runtime.

Inputs: no named parameters. Returns: result

runtime_stopA

End the Colab/Kaggle session started with colab_runtime_start / kaggle_runtime_start.

Download or push results first (save_checkpoint / hf_push_run). On Kaggle this stops the GPU-hours clock, and the files in /kaggle/working stay on Kaggle as the notebook's output. (A Hugging Face machine is stopped with hf_runtime_stop.)

Inputs: no named parameters. Returns: result

save_checkpointA

Download a run's checkpoint(s) to the local machine so they survive VM shutdown.

filename: a single file in the run's checkpoints/ dir; if blank, the whole checkpoints/ dir is zipped on the runtime and downloaded. For a Hugging Face job the checkpoints come from the run's Hub repo instead.

Inputs: run_name (required), filename. Returns: result

setup_guideA

How to connect a place to run on: "colab", "kaggle", "huggingface" or "space".

With no platform it reports what is already set up and what is missing. Use this whenever the user asks how to connect, or a tool says nothing is connected.

Inputs: platform. Returns: result

stop_runB

Terminate a running training job (for a Hugging Face job this stops its billing).

Inputs: run_name (required). Returns: result

upload_fileB

Upload a local file to the runtime (path is relative to the runtime's contents root).

Inputs: local_path (required), remote_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 54 tools

    Disambiguation3/5

    Several tool families overlap in purpose: launch_training vs hf_job_launch, connect_runtime vs hf_runtime_connect vs hf_runtime_start, and upload_file/download_file vs hf_upload/hf_download/hf_push_run all target similar actions across different backends. The long descriptions do clarify the distinctions (connected runtime vs rented HF job, local vs Hub vs runtime paths), which keeps it usable, but an agent must read carefully to choose correctly.

    Naming Consistency3/5

    All names are snake_case, which is good, but the convention is mixed: some tools are domain-prefixed (hf_, kaggle_, colab_, cv_, rl_, notebook_) while others are bare verbs (run_code, launch_training, stop_run, fetch_image). The prefix scheme is readable and mostly predictable, but verbs are inconsistent (launch vs start vs connect, run vs execute).

    Tool Count2/5

    54 tools is far above the 3-15 sweet spot and well past the 25+ 'heavy' threshold. While the server genuinely spans Colab, Kaggle, HF jobs, HF Spaces, notebooks, RL and CV helpers, several tools could be consolidated (e.g. separate start/connect/stop per backend, separate get_logs/get_metrics/get_run_status), making the surface feel sprawling.

    Completeness4/5

    Coverage is strong across the whole lifecycle: runtime start/connect/stop, code execution, file transfer, notebook editing, training launch/poll/stop, checkpoints, metrics plotting, Kaggle competition submission, HF Hub upload/download, and Space management. Minor gaps exist (no remote directory listing, no repo delete, no HF job log helper distinct from run logs), but agents can work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible AI assistants to run Python code on Google Colab GPU/TPU runtimes, supporting accelerators like T4, A100, H100, with background execution and Google Drive integration.
      10
      3
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables LLMs to manage and run machine learning training jobs on a remote server, including syncing code, submitting experiments, monitoring progress, reading TensorBoard metrics, and receiving completion notifications.
      -