cloudgpu-mcp 0.14.0 → 0.14.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +3 -2
- package/skills/cloudgpu/SKILL.md +95 -0
- package/skills/cloudgpu-model-api/SKILL.md +56 -0
- package/src/cli-core.js +3 -3
- package/src/index.js +1 -1
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "cloudgpu-mcp",
|
|
3
|
-
"version": "0.14.
|
|
3
|
+
"version": "0.14.1",
|
|
4
4
|
"mcpName": "io.github.cloudgpu-app/cloudgpu-mcp",
|
|
5
5
|
"description": "MCP server and command-line tool for cloudgpu.app: let Claude Code, Cursor, Cline, opencode, goose and other MCP clients (or you, from a terminal) rent a GPU with explicit billing quotes, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
|
|
6
6
|
"type": "module",
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
"rules",
|
|
15
15
|
"README.md",
|
|
16
16
|
"LICENSE",
|
|
17
|
-
"examples"
|
|
17
|
+
"examples",
|
|
18
|
+
"skills"
|
|
18
19
|
],
|
|
19
20
|
"engines": {
|
|
20
21
|
"node": ">=18.3"
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cloudgpu
|
|
3
|
+
description: Rent and use a cloud GPU on CloudGPU (cloudgpu.app) through the `cloudgpu` MCP tools. Use when the user wants to rent a GPU, run a training, fine-tuning, inference or ComfyUI job on a cloud GPU, or mentions CloudGPU or cloudgpu.app, and the `cloudgpu` MCP tools are available.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CloudGPU
|
|
7
|
+
|
|
8
|
+
Follow these steps whenever you rent or use a GPU on CloudGPU (cloudgpu.app) through the `cloudgpu` MCP tools.
|
|
9
|
+
|
|
10
|
+
## Before renting
|
|
11
|
+
|
|
12
|
+
1. Call `get_account` and `list_gpus`. Pick a GPU with enough VRAM for the job, and don't rent more GPU than the job needs. As a rough guide, LoRA on a 7–8B model fits in 24 GB, and a full fine-tune of the same model needs 80 GB or more.
|
|
13
|
+
2. Check existing `list_instances` before renting. A compatible running rental can run multiple approved commands inside its original limits. Optionally compare billed task costs with `compare_compute_costs`, then call `estimate_cost` with preparation/download/output time included.
|
|
14
|
+
3. Show the user a short quote before you rent anything:
|
|
15
|
+
- the GPU and how many,
|
|
16
|
+
- the price per hour,
|
|
17
|
+
- the billing increment and minimum charge: some sources charge a minimum one hour and every started hour in full, with no voluntary-stop refund of unused charged time,
|
|
18
|
+
- the estimated hours and cost,
|
|
19
|
+
- the budget and time limit you will set,
|
|
20
|
+
- their balance after the job.
|
|
21
|
+
4. Rent only after the user says yes. Pass `user_confirmed=true` only in that case.
|
|
22
|
+
|
|
23
|
+
## Renting
|
|
24
|
+
|
|
25
|
+
- Always set `max_spend_usd` and `max_hours`. CloudGPU's servers destroy the instance when either is reached, even if you have disconnected.
|
|
26
|
+
- Keep `idle_minutes` on (default 60). Include setup time when agreeing limits before creation. Never silently extend the approved budget, time or idle limits.
|
|
27
|
+
- Call `get_status` at intervals, not in a tight loop, until the instance is `running`.
|
|
28
|
+
- On failure, inspect actual charges and release status; do not promise zero charges or automatic refunds. Do not retry creation while the result or resource release is uncertain.
|
|
29
|
+
|
|
30
|
+
## Working on the instance
|
|
31
|
+
|
|
32
|
+
- Put code and data on the instance with `upload`. Do not upload credentials.
|
|
33
|
+
- Use `run_command` for short steps. For training, long installs or big downloads, use `background=true` and follow progress with `tail_logs`.
|
|
34
|
+
- Instances come with Python and CUDA, but not always PyTorch. Check first: `nvidia-smi -L` and `python -c "import torch; print(torch.__version__, torch.cuda.is_available())"`.
|
|
35
|
+
- If PyTorch is missing, plain `pip install torch` installs a current CUDA build. It is a few GB, so run it with `background=true`. Index URLs for older CUDA versions (for example `.../whl/cu124`) may have no wheel for the machine's Python, which can be very new. Only use them if the project needs that CUDA version, and then create an environment with an older Python first (`conda create -y -n work python=3.12`, then `conda activate work && ...` in each command).
|
|
36
|
+
- If `nvidia-smi` shows no GPU once the instance is running, stop and tell the user. CloudGPU detects such machines and shuts them down automatically.
|
|
37
|
+
- **Do not** change the root password, edit the SSH configuration, change the firewall, or stop the platform's monitoring agent (`cgpu-*` processes). The platform must keep its access to the instance; if that access is lost, the platform shuts the instance down. The MCP server refuses such commands.
|
|
38
|
+
- Never use the GPU for cryptocurrency mining or anything the [acceptable use policy](https://cloudgpu.app/aup) forbids. Instances that do so are shut down.
|
|
39
|
+
|
|
40
|
+
## Finishing (always)
|
|
41
|
+
|
|
42
|
+
1. Download every result: model weights, adapters, checkpoints, logs, metrics. Destroying an instance erases its disk. Workspace persists only files explicitly uploaded and ready, under its quota/retention policy. It is not an automatic disk backup. Storage fees are separate from GPU budgets.
|
|
43
|
+
2. Call `stop_instance`.
|
|
44
|
+
3. Tell the user what ran, where the results are on their computer, and the final cost from `stop_instance`.
|
|
45
|
+
|
|
46
|
+
If anything goes wrong mid-way, do not leave the instance running. Download whatever exists, stop the instance, then explain what happened.
|
|
47
|
+
|
|
48
|
+
## Balance and top-ups
|
|
49
|
+
|
|
50
|
+
- If `get_account` or `estimate_cost` shows the balance would not cover the quoted job, do not call `create_instance`. Tell the user how much is missing and ask them to top up at https://cloudgpu.app/billing (card or USDT). When they say it is done, call `estimate_cost` again before renting.
|
|
51
|
+
- `create_instance` also checks the balance. If it is below the estimate or budget plus 10%, the MCP server does not rent anything and returns an error that starts with `Not rented: balance $... is below $...` and points to https://cloudgpu.app/billing. If the CloudGPU API itself rejects the request with HTTP status 402, the error reads `CloudGPU API error 402 <code>: <message>` followed by the same billing link. Handle both the same way as above: stop, tell the user how much is missing, and do not retry.
|
|
52
|
+
- Never top up, enter card details or move money on the user's behalf. The user does that themselves on the billing page.
|
|
53
|
+
|
|
54
|
+
## Checking prices without the MCP server
|
|
55
|
+
|
|
56
|
+
If the `cloudgpu` tools are not available, read current prices from https://cloudgpu.app/gpu-prices.json (machine-readable, with an `updated_at` field) or https://cloudgpu.app/pricing. Check `updated_at` and tell the user how fresh the data is. Do not quote prices from memory.
|
|
57
|
+
|
|
58
|
+
## Optional persistence
|
|
59
|
+
|
|
60
|
+
Discover tools and `GET /v1/public/compute-capabilities` first. Persistence is
|
|
61
|
+
unavailable when that endpoint is missing or `storage` is false. Never promise
|
|
62
|
+
free storage, a retention period or automatic output collection.
|
|
63
|
+
|
|
64
|
+
When enabled, ask before saving private project files. Use `save_workspace` for
|
|
65
|
+
regular source/config/dependency-manifest files, `upload_artifact` for persistent
|
|
66
|
+
results or datasets/models, and `download_artifact` to retrieve them. Pass the
|
|
67
|
+
saved `workspace_version_id` to `run_job` to restore the files before execution.
|
|
68
|
+
The service does not restore a boot disk and does not automatically save edits;
|
|
69
|
+
the Job command must still save its results before shutdown. Do not upload secrets.
|
|
70
|
+
|
|
71
|
+
For Jobs, prefer `quote_compute` for a server quote and send its `quote_id` with
|
|
72
|
+
the chosen candidate. Its `required_starting_balance` is separate from the task
|
|
73
|
+
estimate. The original `estimate_cost` quote belongs to `create_instance`.
|
|
74
|
+
|
|
75
|
+
## Only need a model, not a GPU?
|
|
76
|
+
|
|
77
|
+
The same API key works for CloudGPU's model API at `https://cloudgpu.app/v1`. Call `list_models` to see the models. If you only need inference on a hosted model, use the API instead of renting a GPU.
|
|
78
|
+
|
|
79
|
+
## If the MCP server is not installed
|
|
80
|
+
|
|
81
|
+
If no `cloudgpu` tools are available, the MCP server needs to be set up first:
|
|
82
|
+
|
|
83
|
+
- Command: `npx -y cloudgpu-mcp`
|
|
84
|
+
- Environment variable: `CLOUDGPU_API_KEY`, with a key created at https://cloudgpu.app.
|
|
85
|
+
- Never paste the key into the chat or into files in the project. Ask the user to put it in their MCP client's configuration or environment themselves.
|
|
86
|
+
|
|
87
|
+
See the [README](https://github.com/cloudgpu-app/cloudgpu-mcp#install) for per-client setup.
|
|
88
|
+
|
|
89
|
+
## Jobs and instance reuse
|
|
90
|
+
|
|
91
|
+
Sequential approved `run_command` calls may reuse a running rental within its original budget, deadline and idle limit. Check ownership, readiness and free memory/disk first. Independent `run_job` calls and `prepare_job_rerun` provision separately, not into that live rental. Job/template support is configuration-specific; inspect `supports_jobs` and obtain a Job quote, never substitute the rental quote. Do not keep an idle GPU merely to consume a prepaid hour. Confirm result persistence and release when finished.
|
|
92
|
+
|
|
93
|
+
## Connect with an approval link
|
|
94
|
+
|
|
95
|
+
In a configured MCP client, call `connect_account`, show the owner its link, then `finish_connect` after approval. No password or API key is pasted in chat. The link grants scoped access; it does not automatically install an MCP server in arbitrary AI products.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: cloudgpu-model-api
|
|
3
|
+
description: Call a hosted model through CloudGPU's OpenAI-compatible model API at https://cloudgpu.app/v1, without renting a GPU. Use when the user wants to call a hosted model (chat/completions) through CloudGPU, wire CloudGPU into an OpenAI-compatible client or agent framework (OpenAI SDK, LangChain, Cline, Roo Code, Continue, Aider, n8n, Dify), or mentions cloudgpu.app/v1.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# CloudGPU model API
|
|
7
|
+
|
|
8
|
+
CloudGPU (cloudgpu.app) serves hosted models over an OpenAI-compatible API at `https://cloudgpu.app/v1`. No GPU rental is needed.
|
|
9
|
+
|
|
10
|
+
## 1. Pick a model ID
|
|
11
|
+
|
|
12
|
+
- Call the `list_models` tool, or `GET https://cloudgpu.app/v1/models` (public, no key needed).
|
|
13
|
+
- Never guess or hardcode a model ID. Use one the list returns.
|
|
14
|
+
|
|
15
|
+
## 2. Authenticate
|
|
16
|
+
|
|
17
|
+
- Send `Authorization: Bearer $CLOUDGPU_API_KEY`.
|
|
18
|
+
- Read the key from the environment. Never print it, and never write it into files that get committed.
|
|
19
|
+
- If `CLOUDGPU_API_KEY` is not set, ask the user to create a key at https://cloudgpu.app and set it themselves. Do not ask them to paste it into the chat.
|
|
20
|
+
|
|
21
|
+
## 3. Set up a client
|
|
22
|
+
|
|
23
|
+
In any OpenAI-compatible SDK, client or agent framework, set `base_url` to `https://cloudgpu.app/v1` and the API key to the value of `CLOUDGPU_API_KEY`.
|
|
24
|
+
|
|
25
|
+
Python (OpenAI SDK):
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import os
|
|
29
|
+
from openai import OpenAI
|
|
30
|
+
|
|
31
|
+
client = OpenAI(base_url="https://cloudgpu.app/v1", api_key=os.environ["CLOUDGPU_API_KEY"])
|
|
32
|
+
resp = client.chat.completions.create(
|
|
33
|
+
model="kimi-k3", # example only: check list_models or /v1/models first
|
|
34
|
+
messages=[{"role": "user", "content": "Say hello."}],
|
|
35
|
+
)
|
|
36
|
+
print(resp.choices[0].message.content)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The same request as HTTP. Read the key from the environment; do not paste it into the request text you show the user.
|
|
40
|
+
|
|
41
|
+
- `POST https://cloudgpu.app/v1/chat/completions`
|
|
42
|
+
- `Authorization: Bearer` followed by the value of `CLOUDGPU_API_KEY`
|
|
43
|
+
- `Content-Type: application/json`
|
|
44
|
+
- Body: `{"model":"<id from the model list>","messages":[{"role":"user","content":"Say hello."}]}`
|
|
45
|
+
|
|
46
|
+
The model id in any example is only an example. Check the model list before using it.
|
|
47
|
+
|
|
48
|
+
## Prices and balance
|
|
49
|
+
|
|
50
|
+
Don't quote prices from memory. Current prices are at https://cloudgpu.app/api. The same API key and balance also cover GPU rental (see the `cloudgpu` skill).
|
|
51
|
+
|
|
52
|
+
## Errors
|
|
53
|
+
|
|
54
|
+
- **401:** the key is missing or wrong. Check that `CLOUDGPU_API_KEY` is set and valid.
|
|
55
|
+
- **404 / model not found:** the model ID is not available. Re-run `list_models` and use an ID from the list.
|
|
56
|
+
- **429:** too many requests. Back off, then retry.
|
package/src/cli-core.js
CHANGED
|
@@ -78,7 +78,7 @@ const COMMANDS = {
|
|
|
78
78
|
" output in /root/cloudgpu-setup.log on the instance",
|
|
79
79
|
"--wait poll until the instance is running or failed, then print SSH and URLs",
|
|
80
80
|
"--show-password with --wait, also print the SSH password if the API returns one",
|
|
81
|
-
"Costs money: billing is
|
|
81
|
+
"Costs money: billing is source-specific. Hourly sources require a billing quote and explicit approval through MCP; never infer billing from the hourly price label.",
|
|
82
82
|
],
|
|
83
83
|
options: {
|
|
84
84
|
...JSON_OPT,
|
|
@@ -557,7 +557,7 @@ async function cmdOffers(c) {
|
|
|
557
557
|
offers.map((o) => [o.gpu_model, o.vram_gb != null ? `${o.vram_gb} GB` : null, usd(o.hourly_usd), o.available, o.min_gpu_count]),
|
|
558
558
|
),
|
|
559
559
|
);
|
|
560
|
-
c.out("Prices and availability are live
|
|
560
|
+
c.out("Prices and availability are live and can change; billing periods vary by source. Use MCP estimate_cost for the minimum charge.\n");
|
|
561
561
|
if (tpl && tpl.recommended_gpu) c.out(`Template ${tpl.id} recommends: ${tpl.recommended_gpu}\n`);
|
|
562
562
|
return 0;
|
|
563
563
|
}
|
|
@@ -611,7 +611,7 @@ async function cmdUp(c) {
|
|
|
611
611
|
return 0;
|
|
612
612
|
}
|
|
613
613
|
c.out(`Created ${inst.id} (${gpuLabel(inst)}, status: ${inst.status}).\n`);
|
|
614
|
-
c.out(`Billing
|
|
614
|
+
c.out(`Billing follows the approved source-specific terms until destroyed. Check it with: cloudgpu status ${inst.id}\n`);
|
|
615
615
|
c.out(`Destroy it with: cloudgpu down ${inst.id}\n`);
|
|
616
616
|
return 0;
|
|
617
617
|
}
|
package/src/index.js
CHANGED