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.

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.

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

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