MCP server · CLI · Local API

Measure what your code
does to your Mac.

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.

claude — ~/projects/image-api
claude — ~/projects/video-render
How it works

One question. Three answers.

go

Start the job

Cool, enough free memory, GPU and CPU have room.

wait

Hold on

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).

no

Don't start

Not enough memory even after closing big apps. Try a smaller batch or model.

Setup

Connect in one line.

The MCP server is built into the Thermo app. Nothing else to install. Install Thermo, then pick your tool.

Plugin (recommended)

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

MCP server only

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"] }
  }
}
SettingValue
Transportstdio
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."

Tools

Nine tools. All read-only.

Thermo never changes anything on your Mac through MCP. It reads and reports.

start_benchmark
label: string
process: string (optional)
interval_seconds: 0.5–10 (1)

Start 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_benchmark
id: string (optional)

Stops 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_headroom
kind: any | gpu | cpu | memory
memory_gb: number

Call this before heavy work. Returns gowaitno with reasons, tips and which apps to close.

wait_until_cool
target_celsius: 40–100 (70)
timeout_seconds: 5–1800 (300)

Blocks until the Mac reaches the target temperature, or the timeout passes.

get_status

CPU, GPU, memory and pressure, hottest temperature, throttling, battery, and a one-line health summary.

get_temperatures

Every part: CPU performance and efficiency cores, GPU, memory, SSD, battery, Wi-Fi, palm rest, each with ok / warm / hot.

get_top_processes
limit: 1–50 (8)
sort_by: cpu | memory

Busiest apps, with project folders for dev tools like node and python.

get_battery

Health %, condition, cycles, charge, charging state, watts and time left.

get_history
range: 1h | 24h

Per-minute CPU, memory, GPU, temperature and battery, with averages, peaks and the daily battery-health log.

Example: 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 }
}
Command line

For scripts and humans.

The same readings in Terminal. Plain text for you, --json for scripts. Homebrew adds thermo automatically; zip users: ⚙ → Connections → Install thermo command.

CommandGives you
thermo statusOverview and health line
thermo tempsEvery part's temperature
thermo apps --sort memoryBusiest apps
thermo batteryHealth, cycles, watts
thermo history --range 24hAverages and peaks
thermo headroom --kind gpuExit 0 go · 3 wait · 4 no
thermo wait-cool --target 70Waits, then returns
thermo bench -- npm testRuns a command, reports load, heat rise, throttling
thermo mcpStarts the MCP server

Benchmark any command

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

Gate any script

# wait for room before training
thermo headroom --kind gpu --memory-gb 12 \
  || thermo wait-cool --target 70
python train.py

Without Homebrew

/Applications/Thermo.app/Contents/MacOS/Thermo --cli status --json
Your own apps

Three lines in any language.

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"
EndpointSame as
/v1/statusget_status
/v1/temperaturesget_temperatures
/v1/processes?limit=8&sort=cpuget_top_processes
/v1/batteryget_battery
/v1/history?range=24hget_history
/v1/headroom?kind=gpu&memory_gb=8check_headroom
GitHub Actions

Check your Mac runners.

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
FAQ

Good questions.

Does the agent get access to my files or apps?

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.

Does Thermo need to be running?

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.

Does it work in cloud agents or on Linux/Windows?

Not yet: Thermo reads Mac hardware, so it runs where your Mac is. Windows and Linux support is next on the roadmap.

Does it use the network?

No. MCP and the CLI talk over standard input/output only. The optional API listens on 127.0.0.1, never on your network.

The server doesn't show up in my client.

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.