gpu-bridge
Connects to a free Google Colab GPU runtime via a single pasted line in a notebook cell, then runs code, uploads/downloads files, and executes training runs on that remote machine.
Rents Hugging Face GPU machines and jobs on a per-minute basis with time limits and idle shutdown, and provides Hub tools: searching and downloading models/datasets, uploading files, pushing run artifacts to private repos, and managing Spaces (status, hardware, pause, restart).
Starts and manages free Kaggle GPU sessions, runs training scripts in the background, and provides tools for Kaggle competitions: searching datasets, attaching competition files, submitting predictions, and checking submissions and leaderboards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gpu-bridge Connect a Kaggle GPU and train a baseline on the Titanic dataset"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 minuteRequirements: 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 | iexInside 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:
downloads gpu-bridge to
~/.gpu-bridge/app(installinguvfirst if needed),creates an isolated Python environment from the locked dependencies,
registers the server with every supported AI client it finds,
adds a
gpu-bridgecommand to yourPATH.
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 |
| Automatic |
Google Colab | Free | None | You run one pasted line in a Colab cell |
Hugging Face | Paid per minute |
| 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 |
| Records numbers for the status, metrics and plot tools. |
| Keeps a file or folder as a checkpoint. |
| The run's working folder. |
| The run's seed, set by seed sweeps. |
Examples:
examples/llm_lora_finetune.py: LoRA fine-tune of a language model
examples/rl_cartpole.py: PPO on CartPole
examples/cv_mnist.py: a small CNN on MNIST
The assistant can also fetch them with the example_script tool.
Tools
The server exposes 54 tools.
Group | Tools |
Get a machine |
|
Hugging Face machines |
|
Run code and files |
|
Training runs |
|
Notebooks |
|
Reinforcement learning |
|
Computer vision |
|
Kaggle competitions |
|
Hugging Face Hub and Spaces |
|
Help |
|
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 URLgpu-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 |
| 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. |
| Installer only: where the app is installed. Default |
| Installer only: where the |
| Installer only: branch to install. Default |
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_listshows anything still running.hf_hardwareshows 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 --httphas 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 |
"No Kaggle login found" | Run |
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 |
"No Hugging Face token found" | Run |
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 clientsThe 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 suiteLicense
MIT, see LICENSE.
Available Tools
54 toolscolab_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_searchA
Search the Hugging Face Hub for models or datasets, most downloaded first.
kind: "model" or "dataset".
Inputs: query (required), kind, limit. 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
Scored across 54 tools
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.
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).
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.
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
Related MCP Connectors
AI cloud for agents: launch GPUs, run jobs that stop their own billing, schedule runs.
GPU compute for agents: run commands on an L4/A100/H100, watch logs, billed per second.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
Rent GPUs at live prices and serve any Hugging Face model, with spend caps for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.103MIT
- AlicenseNot gradedqualityDmaintenanceEnables running GPU-accelerated Python code on Kaggle from any MCP-compatible AI assistant without local GPU hardware.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to autonomously manage Google Colab GPU sessions, submit and monitor training jobs, and debug/fix issues via an encrypted tunnel without requiring a browser tab.MIT
- FlicenseNot gradedqualityBmaintenanceEnables 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.-