coolercontrol-mcp
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., "@coolercontrol-mcp what are my current CPU and GPU temperatures and fan speeds?"
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.
coolercontrol-mcp
An MCP server for CoolerControl. It lets Claude and other MCP clients read your temperatures and fan speeds, and change fan profiles, fixed speeds and modes, through the CoolerControl daemon's REST API.
Tested against CoolerControl 5.1.1.
Tools
All 32 tools. ✏️ marks tools that change something; they need a token with Write Access.
Area | Tool | What it does |
Monitoring |
| Latest temperatures (°C), fan rpm and duty, power and clocks; optionally one device or channel |
| Devices, their fan channels and their temperature sensors | |
| What each fan channel is set to: a profile, a fixed duty, or the default | |
| Daemon version, uptime and warning count | |
Fan channels |
| Set a channel to a fixed duty % (refuses values below |
| Assign a profile to a channel | |
| Return a channel to its hardware default | |
Profiles |
| Profiles with their curves and temperature sources |
| Create a Fixed, Graph, Mix or Overlay profile | |
| Change some fields of a profile; the rest stay as they are | |
| Delete a profile; refuses while anything uses it unless | |
Modes |
| Saved modes and which one is active |
| The channel settings saved in a mode | |
| Save the current settings of every channel as a new mode | |
| Rename a mode and/or re-save it from the current settings | |
| Copy a mode | |
| Delete a mode | |
| Apply a mode's saved settings | |
Functions |
| Functions that control how quickly profiles change duty |
| Create a function; unset fields copy the Default Function | |
| Change some fields of a function | |
| Delete a function; refuses while a profile uses it unless | |
Alerts |
| Alerts and the recent alert log |
| Create an alert on a temperature, duty, load, rpm or frequency | |
| Change some fields of an alert | |
| Delete an alert | |
Custom sensors |
| Custom sensors |
| Create a sensor that mixes, offsets or averages other sensors, or reads a file | |
| Change some fields of a custom sensor | |
| Delete a custom sensor; refuses while a profile uses it unless | |
Any other endpoint |
| List the 83 REST endpoints a token can call |
| Call any of them: lighting, LCD images, calibration, name overrides, daemon settings, stats, detection, power profiles, logs, metrics |
Devices can be given by uid, uid prefix (8+ characters) or exact name. Channels can be given by name (fan1) or label (Intake). Profiles, modes, functions and alerts can be given by uid or name.
Not supported: login and passwords, access-token management, daemon shutdown, plugins, stress tests, saving UI settings and the live event streams. CoolerControl accepts only a browser session for these, not a token.
Related MCP server: daikin-remote-mcp
Setup
Create a token. In the CoolerControl UI, open Access Protection → Create Token. Leave Write Access off for a monitoring-only token; the daemon then rejects the write tools with a clear error. Turn it on to let the client change fan settings.
Build:
git clone https://github.com/ryanpag3/coolercontrol-mcp.git cd coolercontrol-mcp npm install # also builds dist/Register it with your MCP client.
Claude Code:
claude mcp add coolercontrol -s user \ -e COOLERCONTROL_TOKEN=cc_... \ -- node /path/to/coolercontrol-mcp/dist/index.jsClaude Desktop (or any client that uses a JSON config):
{ "mcpServers": { "coolercontrol": { "command": "node", "args": ["/path/to/coolercontrol-mcp/dist/index.js"], "env": { "COOLERCONTROL_TOKEN": "cc_..." } } } }
Docker
A multi-arch image (amd64, arm64) is published to GHCR. The daemon listens on 127.0.0.1 by default, so the container needs --network host to reach it:
claude mcp add coolercontrol -s user -e COOLERCONTROL_TOKEN=cc_... -- \
docker run -i --rm --network host -e COOLERCONTROL_TOKEN ghcr.io/ryanpag3/coolercontrol-mcp:latest{
"mcpServers": {
"coolercontrol": {
"command": "docker",
"args": ["run", "-i", "--rm", "--network", "host", "-e", "COOLERCONTROL_TOKEN",
"ghcr.io/ryanpag3/coolercontrol-mcp:latest"],
"env": { "COOLERCONTROL_TOKEN": "cc_..." }
}
}
}Tags: latest (master), sha-<commit>, and X.Y.Z / X.Y for vX.Y.Z git tags.
Configuration
Variable | Default | |
| (required) |
|
|
| Daemon URL. Use |
|
| Lowest duty % that |
|
| Accept self-signed certificates |
The minimum-duty floor applies only to set_fixed_speed. Profiles keep whatever curve you gave them in CoolerControl.
Development
npm run build # tsc → dist/
npm test # vitest
npx @modelcontextprotocol/inspector -e COOLERCONTROL_TOKEN=cc_... node dist/index.jsLicense
MIT
Available Tools
32 toolsactivate_modeActivate modeAIdempotent
Activate a saved mode (see list_modes), applying all of its channel settings.
Inputs: mode (required).
apply_profileApply fan profileAIdempotent
Assign an existing profile (see list_profiles) to a fan/pump channel. Returns the previous setting.
Inputs: device (required), channel (required), profile (required).
call_apiCall CoolerControl APIADestructive
Call any endpoint from list_api_endpoints directly. Prefer the dedicated tools when one fits; they validate inputs. Non-GET calls change daemon state and need a token with Write Access.
Inputs: path (required), method (required), body, form, +2 more.
create_alertCreate alertB
Create a alert. Required: name, min, max, warmup_duration (s), channel_sources: [{device_uid, channel_name, channel_metric}] where channel_metric is Temp | Duty | Load | RPM | Freq (all sources share one metric; channel_name is the sensor/channel name, e.g. temp1 or fan1). Optional: cooldown_duration, repeat_interval, enabled, desktop_notify, desktop_notify_audio, desktop_notify_recovery, shutdown_on_activation.
Inputs: fields (required).
create_custom_sensorCreate custom_sensorB
Create a custom sensor. Required: id (unique; becomes the sensor's name) and cs_type. cs_type Mix: mix_function (Min | Max | Delta | Avg | WeightedAvg | Sum) and sources: [{temp_source: {device_uid, temp_name}, weight}]. File: file_path. Offset: offset, optional scale, one source. TimeAverage / ExponentialMovingAvg: time_window_seconds (1-300), one source. Optional metric (Temp default; Duty | Load | RPM | Freq use channel_source instead of temp_source in sources).
Inputs: fields (required).
create_functionCreate functionA
Create a function. Required: name. Unset fields copy the Default Function. Common fields: f_type (Identity | Standard), duty_minimum / duty_maximum (step size per change, %), step_size_min_decreasing / step_size_max_decreasing, threshold_hopping, bypass_min_at_extremes; Standard also takes deviance, response_delay, only_downward.
Inputs: fields (required).
create_modeCreate modeB
Save the current settings of every channel as a new mode, which activate_mode can restore later.
Inputs: name (required).
create_profileCreate fan profileA
Create a fan profile. Fixed: a constant duty. Graph: a temperature→duty curve following one sensor. Mix: combines member profiles (Min/Max/Avg/Diff/Sum). Overlay: offsets one base profile. Assign it to a channel afterwards with apply_profile.
Inputs: name (required), type (required), curve, offset, +5 more.
delete_alertDelete alertCDestructive
Delete a alert.
Inputs: alert (required).
delete_custom_sensorDelete custom_sensorADestructive
Delete a custom sensor. Refuses if it is in use unless force is true.
Inputs: custom_sensor (required), force.
delete_functionDelete functionADestructive
Delete a function. Refuses if it is in use unless force is true.
Inputs: function (required), force.
delete_modeDelete modeADestructive
Delete a saved mode. Channel settings currently applied are not changed.
Inputs: mode (required).
delete_profileDelete fan profileADestructive
Delete a profile. Refuses if any channel, Mix/Overlay profile or mode uses it, listing where, unless force is true; with force, channels using it fall back to their default and modes drop it.
Inputs: profile (required), force.
duplicate_modeDuplicate modeB
Copy a mode, including its saved settings.
Inputs: mode (required).
get_channel_settingsFan channel settingsARead-only
What each speed-controllable channel is set to: a profile (by name), a fixed duty, or the default. Covers all devices unless one is given.
Inputs: device.
get_healthDaemon healthBRead-only
CoolerControl daemon health: version, uptime, warning/error counts.
Inputs: no named parameters.
get_modeGet modeCRead-only
The channel settings saved in a mode, with device and profile names.
Inputs: mode (required).
get_statusCurrent temperatures and fan speedsARead-only
Latest sensor readings: temperatures (°C), fan rpm, duty (%), power (W) and frequencies (MHz). Optionally limited to one device and channel.
Inputs: raw, device, channel.
list_alertsList alertsCRead-only
Configured alerts and the recent alert log.
Inputs: no named parameters.
list_api_endpointsList CoolerControl API endpointsARead-only
Every CoolerControl 5.1.1 REST endpoint a token can call, for use with call_api: lighting, LCD, calibrations, name overrides, daemon settings, stats, hardware detection, power profiles, ThinkPad / AMD overdrive, logs, metrics and the endpoints behind the other tools. Filter by tag or text.
Inputs: tag, search.
list_custom_sensorsList custom sensorsCRead-only
User-defined custom sensors (mixes of other temps, or file-based sensors).
Inputs: no named parameters.
list_devicesList devicesARead-only
List hardware CoolerControl knows about (CPU, GPUs, fan hubs, AIOs, PSUs, drives) with their speed-controllable channels and temperature sensors. Use the uids and channel names here for other tools.
Inputs: raw.
list_functionsList profile functionsBRead-only
Functions that shape how profiles apply duty changes (min/max duty, step sizes, hysteresis).
Inputs: no named parameters.
list_modesList modesARead-only
Saved modes (snapshots of all channel settings) and which one is active.
Inputs: no named parameters.
list_profilesList fan profilesBRead-only
Fan profiles (fixed, graph curves temp→duty, mixes) with their temperature source.
Inputs: raw.
reset_channelReset fan channelAIdempotent
Reset a fan/pump channel to its hardware default, removing any profile or fixed speed. Returns the previous setting.
Inputs: device (required), channel (required).
set_fixed_speedSet fixed fan speedAIdempotent
Set a fan/pump channel to a fixed duty %. Values below 20% are refused (COOLERCONTROL_MIN_DUTY). Returns the previous setting so it can be restored.
Inputs: duty (required), device (required), channel (required).
update_alertUpdate alertAIdempotent
Change fields of an existing alert; fields not given keep their values.
Inputs: alert (required), changes (required).
update_custom_sensorUpdate custom_sensorBIdempotent
Change fields of an existing custom sensor; fields not given keep their values.
Inputs: changes (required), custom_sensor (required).
update_functionUpdate functionBIdempotent
Change fields of an existing function; fields not given keep their values.
Inputs: changes (required), function (required).
update_modeUpdate modeBIdempotent
Rename a mode and/or overwrite its saved settings with the current channel settings.
Inputs: mode (required), name, save_current_settings.
update_profileUpdate fan profileAIdempotent
Change an existing profile. Only the fields given change; a new curve or offset replaces the old one. Changing type requires the new type's fields. Channels using the profile pick up the change immediately.
Inputs: profile (required), name, type, curve, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Tools are grouped by distinct resources and actions (profiles, modes, functions, alerts, custom sensors, channel operations), and most boundaries are clear. The main ambiguity is the generic call_api/list_api_endpoints pair, which overlaps every dedicated tool, but the description explicitly steers agents toward dedicated tools when available.
All tool names use consistent snake_case with predictable verb_noun or action_resource structure. Variations like activate_mode, apply_profile, reset_channel, and set_fixed_speed are specific but still follow the same convention.
32 tools is heavy for a fan-control server, even though the domain has many subresources with full CRUD families. Several conveniences (duplicate_mode) and meta-REST tools push the set beyond a tightly scoped surface, making it borderline over-scoped.
The set covers CRUD for modes, profiles, functions, alerts, and custom sensors, plus device/status reads and channel assignment/reset operations. The list_api_endpoints/call_api escape hatch also fills gaps for lighting, LCD, calibration, and other daemon endpoints.
Related MCP Connectors
Control your Tesla - wake it, warm it up, unlock and more. Get your developer token at https://Infoseek.ai/mcp. Also requires your own Tesla developer token which is tied to your car/fleet.
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for Hubitat Elevation hubs that controls devices via the Maker API, with optional gated access to undocumented admin routes, supporting device listing, command sending, virtual device and hub variable automation for Rule Machine, and hub management features.8MIT
- AlicenseNot gradedqualityCmaintenanceEnables local, cloud-free control of Daikin air conditioners from MCP clients, letting assistants read unit state and adjust power, mode, temperature, fan, louvres, and special modes over the unit's local HTTP API.MIT
- AlicenseAqualityCmaintenanceEnables MCP-compatible clients like Claude Desktop, Claude Code, Codex, and local-model hosts to inspect Proxmox VE clusters, nodes, VMs, containers, storage, snapshots, and tasks, with opt-in write operations for starting, stopping, cloning, backing up, and migrating guests. Read-only by default, it supports both stdio and Streamable HTTP transports.14MIT
- AlicenseNot gradedqualityCmaintenanceConnects MCP clients such as Claude to a NIBE myUplink heat-pump account, letting users list systems and devices, read sensor values and common parameters, check alarms, view smart-home zones, and write settings where scopes allow. Handles the OAuth2 authorization-code and client-credentials flows, refreshing tokens automatically while keeping credentials in a local .env file.MIT