Skip to main content
Glama
coolercontrol-mcp

coolercontrol-mcp

by ryanpag3

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

get_status

Latest temperatures (°C), fan rpm and duty, power and clocks; optionally one device or channel

list_devices

Devices, their fan channels and their temperature sensors

get_channel_settings

What each fan channel is set to: a profile, a fixed duty, or the default

get_health

Daemon version, uptime and warning count

Fan channels

set_fixed_speed ✏️

Set a channel to a fixed duty % (refuses values below COOLERCONTROL_MIN_DUTY)

apply_profile ✏️

Assign a profile to a channel

reset_channel ✏️

Return a channel to its hardware default

Profiles

list_profiles

Profiles with their curves and temperature sources

create_profile ✏️

Create a Fixed, Graph, Mix or Overlay profile

update_profile ✏️

Change some fields of a profile; the rest stay as they are

delete_profile ✏️

Delete a profile; refuses while anything uses it unless force is set

Modes

list_modes

Saved modes and which one is active

get_mode

The channel settings saved in a mode

create_mode ✏️

Save the current settings of every channel as a new mode

update_mode ✏️

Rename a mode and/or re-save it from the current settings

duplicate_mode ✏️

Copy a mode

delete_mode ✏️

Delete a mode

activate_mode ✏️

Apply a mode's saved settings

Functions

list_functions

Functions that control how quickly profiles change duty

create_function ✏️

Create a function; unset fields copy the Default Function

update_function ✏️

Change some fields of a function

delete_function ✏️

Delete a function; refuses while a profile uses it unless force is set

Alerts

list_alerts

Alerts and the recent alert log

create_alert ✏️

Create an alert on a temperature, duty, load, rpm or frequency

update_alert ✏️

Change some fields of an alert

delete_alert ✏️

Delete an alert

Custom sensors

list_custom_sensors

Custom sensors

create_custom_sensor ✏️

Create a sensor that mixes, offsets or averages other sensors, or reads a file

update_custom_sensor ✏️

Change some fields of a custom sensor

delete_custom_sensor ✏️

Delete a custom sensor; refuses while a profile uses it unless force is set

Any other endpoint

list_api_endpoints

List the 83 REST endpoints a token can call

call_api ✏️

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

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

  2. Build:

    git clone https://github.com/ryanpag3/coolercontrol-mcp.git
    cd coolercontrol-mcp
    npm install   # also builds dist/
  3. 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.js

    Claude 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

COOLERCONTROL_TOKEN

(required)

cc_... access token

COOLERCONTROL_URL

http://localhost:11987

Daemon URL. Use https:// for a remote daemon with TLS enabled

COOLERCONTROL_MIN_DUTY

20

Lowest duty % that set_fixed_speed will apply. A guard against stopping a pump or fan by accident; set it to 0 to allow anything the hardware accepts

COOLERCONTROL_INSECURE_TLS

false

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

License

MIT

Available Tools

32 tools
activate_modeActivate modeA
Idempotent

Activate a saved mode (see list_modes), applying all of its channel settings.

Inputs: mode (required).

apply_profileApply fan profileA
Idempotent

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 APIA
Destructive

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 alertC
Destructive

Delete a alert.

Inputs: alert (required).

delete_custom_sensorDelete custom_sensorA
Destructive

Delete a custom sensor. Refuses if it is in use unless force is true.

Inputs: custom_sensor (required), force.

delete_functionDelete functionA
Destructive

Delete a function. Refuses if it is in use unless force is true.

Inputs: function (required), force.

delete_modeDelete modeA
Destructive

Delete a saved mode. Channel settings currently applied are not changed.

Inputs: mode (required).

delete_profileDelete fan profileA
Destructive

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 settingsA
Read-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 healthB
Read-only

CoolerControl daemon health: version, uptime, warning/error counts.

Inputs: no named parameters.

get_modeGet modeC
Read-only

The channel settings saved in a mode, with device and profile names.

Inputs: mode (required).

get_statusCurrent temperatures and fan speedsA
Read-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 alertsC
Read-only

Configured alerts and the recent alert log.

Inputs: no named parameters.

list_api_endpointsList CoolerControl API endpointsA
Read-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 sensorsC
Read-only

User-defined custom sensors (mixes of other temps, or file-based sensors).

Inputs: no named parameters.

list_devicesList devicesA
Read-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 functionsB
Read-only

Functions that shape how profiles apply duty changes (min/max duty, step sizes, hysteresis).

Inputs: no named parameters.

list_modesList modesA
Read-only

Saved modes (snapshots of all channel settings) and which one is active.

Inputs: no named parameters.

list_profilesList fan profilesB
Read-only

Fan profiles (fixed, graph curves temp→duty, mixes) with their temperature source.

Inputs: raw.

reset_channelReset fan channelA
Idempotent

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 speedA
Idempotent

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 alertA
Idempotent

Change fields of an existing alert; fields not given keep their values.

Inputs: alert (required), changes (required).

update_custom_sensorUpdate custom_sensorB
Idempotent

Change fields of an existing custom sensor; fields not given keep their values.

Inputs: changes (required), custom_sensor (required).

update_functionUpdate functionB
Idempotent

Change fields of an existing function; fields not given keep their values.

Inputs: changes (required), function (required).

update_modeUpdate modeB
Idempotent

Rename a mode and/or overwrite its saved settings with the current channel settings.

Inputs: mode (required), name, save_current_settings.

update_profileUpdate fan profileA
Idempotent

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

    A3.5/5.0

    Scored across 32 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP 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.
      8
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      14
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects 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