Connect Thermo to Claude, Codex, Cursor or any MCP client. While your agent runs tests, builds or your app, Thermo records CPU and GPU load, memory and every temperature, then reports the peaks, the heat rise and any throttling. It can also check for headroom before heavy work.
Cool, enough free memory, GPU and CPU have room.
Hot, busy or tight on memory. The agent explains why, offers wait_until_cool, and names what to close (it never quits apps without asking).
Not enough memory even after closing big apps. Try a smaller batch or model.
The MCP server is built into the Thermo app. Nothing else to install. Install Thermo, then pick your tool.
MCP server plus a skill that tells Claude when to check headroom and how to act on it.
/plugin marketplace add simarpreetsingh-019/Thermo /plugin install thermo@thermo
One command in your terminal. Add --scope user to use it in every project.
claude mcp add thermo -- /Applications/Thermo.app/Contents/MacOS/Thermo --mcp
Settings → Developer → Edit Config, add this to claude_desktop_config.json, then restart Claude.
{
"mcpServers": {
"thermo": { "command": "/Applications/Thermo.app/Contents/MacOS/Thermo", "args": ["--mcp"] }
}
}
codex mcp add thermo -- /Applications/Thermo.app/Contents/MacOS/Thermo --mcp
Or in ~/.codex/config.toml:
[mcp_servers.thermo] command = "/Applications/Thermo.app/Contents/MacOS/Thermo" args = ["--mcp"]
Optional: copy the Thermo skill to ~/.codex/skills/thermo/, or paste the AGENTS.md snippet into your project.
Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{
"mcpServers": {
"thermo": { "command": "/Applications/Thermo.app/Contents/MacOS/Thermo", "args": ["--mcp"] }
}
}
Optional rule: save thermo.mdc into .cursor/rules/.
GitHub Copilot agent mode. Add .vscode/mcp.json:
{
"servers": {
"thermo": { "command": "/Applications/Thermo.app/Contents/MacOS/Thermo", "args": ["--mcp"] }
}
}
Windsurf → Settings → Cascade → MCP servers → View raw config (~/.codeium/windsurf/mcp_config.json):
{
"mcpServers": {
"thermo": { "command": "/Applications/Thermo.app/Contents/MacOS/Thermo", "args": ["--mcp"] }
}
}
| Setting | Value |
|---|---|
| Transport | stdio |
| Command | /Applications/Thermo.app/Contents/MacOS/Thermo |
| Arguments | ["--mcp"] |
| Installed in ~/Applications? | ~/Applications/Thermo.app/Contents/MacOS/Thermo |
Works with Zed, Cline, Continue, Goose, LM Studio and any client that speaks MCP.
Then try: "Is my Mac cool enough to train this model? If not, wait until it is."
Thermo never changes anything on your Mac through MCP. It reads and reports.
start_benchmarkStart measuring. Records CPU, GPU, memory and every temperature about once a second while your test, build or app runs. Optionally tracks one process (e.g. node, python).
stop_benchmarkStops and returns the report: CPU/GPU avg, p95 and peak; memory peak and swap growth; temperature start → peak overall and per part; throttling seconds; the tracked process's CPU and memory.
check_headroomCall this before heavy work. Returns gowaitno with reasons, tips and which apps to close.
wait_until_coolBlocks until the Mac reaches the target temperature, or the timeout passes.
get_statusCPU, GPU, memory and pressure, hottest temperature, throttling, battery, and a one-line health summary.
get_temperaturesEvery part: CPU performance and efficiency cores, GPU, memory, SSD, battery, Wi-Fi, palm rest, each with ok / warm / hot.
get_top_processesBusiest apps, with project folders for dev tools like node and python.
get_batteryHealth %, condition, cycles, charge, charging state, watts and time left.
get_historyPer-minute CPU, memory, GPU, temperature and battery, with averages, peaks and the daily battery-health log.
check_headroom response{
"verdict": "wait",
"ok": false,
"kind": "gpu",
"advice": "Better to wait: The Mac is hot (91°C); a heavy job now would run slower.",
"reasons": ["The Mac is hot (91°C); a heavy job now would run slower."],
"tips": ["Wait for it to cool below about 70°C (use wait_until_cool / `thermo wait-cool`)."],
"close_candidates": [{ "name": "Chrome", "cpu_percent": 84.2, "memory_mb": 3120, "pid": 812 }],
"now": { "cpu_percent": 71.4, "gpu_percent": 63, "memory_available_gb": 7.8, "memory_pressure": "normal", "hottest_c": 91.2 }
}
The same readings in Terminal. Plain text for you, --json for scripts. Homebrew adds thermo automatically; zip users: ⚙ → Connections → Install thermo command.
| Command | Gives you |
|---|---|
thermo status | Overview and health line |
thermo temps | Every part's temperature |
thermo apps --sort memory | Busiest apps |
thermo battery | Health, cycles, watts |
thermo history --range 24h | Averages and peaks |
thermo headroom --kind gpu | Exit 0 go · 3 wait · 4 no |
thermo wait-cool --target 70 | Waits, then returns |
thermo bench -- npm test | Runs a command, reports load, heat rise, throttling |
thermo mcp | Starts the MCP server |
thermo bench --process python -- python train.py
# 📊 6 min: CPU avg 64%, GPU avg 91% (peak 100%),
# heat 45→88°C (+43), no throttling, python avg 210% CPU
# wait for room before training
thermo headroom --kind gpu --memory-gb 12 \
|| thermo wait-cool --target 70
python train.py
/Applications/Thermo.app/Contents/MacOS/Thermo --cli status --json
Copy one file. Each client uses the local API when it's on, and the CLI otherwise. Same JSON either way.
thermo_client.py, standard library only.
from thermo_client import Thermo
t = Thermo()
if t.headroom(kind="gpu", memory_gb=8)["verdict"] != "go":
t.wait_until_cool(target=70)thermo.mjs, Node 18+, no dependencies.
import { Thermo } from "./thermo.mjs";
const t = new Thermo();
if ((await t.headroom({ kind: "gpu", memoryGb: 8 })).verdict !== "go")
await t.waitUntilCool({ target: 70 });Thermo.swift, Foundation only.
let t = ThermoClient()
let h = try await t.headroom(kind: "gpu", memoryGB: 8)
if h["verdict"] as? String != "go" { _ = try await t.waitUntilCool(target: 70) }Turn it on in Thermo: ⚙ → Connections → Local API for other apps. Localhost only, read-only, token-protected; requests from web pages are refused.
TOKEN=$(python3 -c "import json,os;print(json.load(open(os.path.expanduser('~/Library/Application Support/Thermo/api.json')))['token'])")
curl -H "Authorization: Bearer $TOKEN" "http://127.0.0.1:47615/v1/headroom?kind=gpu&memory_gb=8"
| Endpoint | Same as |
|---|---|
/v1/status | get_status |
/v1/temperatures | get_temperatures |
/v1/processes?limit=8&sort=cpu | get_top_processes |
/v1/battery | get_battery |
/v1/history?range=24h | get_history |
/v1/headroom?kind=gpu&memory_gb=8 | check_headroom |
Writes a load and temperature table to the job summary, outputs verdict, and can wait for the runner to cool or fail the step. Best on self-hosted Mac runners.
jobs:
render:
runs-on: [self-hosted, macOS]
steps:
- uses: simarpreetsingh-019/Thermo@v1
id: thermo
with:
kind: gpu # any | gpu | cpu | memory
memory-gb: 6
wait-cool: 75 # optional
fail-on: no # never | wait | no
- run: ./render.sh
No. All seven tools are read-only system readings. Thermo can't open, change or quit anything through MCP. App names and project folder names are included in process lists; turn that off in ⚙ → Connections → Share app names.
No. The MCP server and CLI take their own readings. The Thermo app is only needed for the local HTTP API and for recording history.
Not yet: Thermo reads Mac hardware, so it runs where your Mac is. Windows and Linux support is next on the roadmap.
No. MCP and the CLI talk over standard input/output only. The optional API listens on 127.0.0.1, never on your network.
Check the path exists: ls /Applications/Thermo.app/Contents/MacOS/Thermo. Run thermo status to make sure readings work. In Claude Code, claude mcp list should show thermo ✔ Connected. Still stuck? Open an issue.