@mhdd_24/caffeine-mcp

MCP server that controls Zhorn Caffeine on Windows so your PC stays awake (no sleep / screensaver). Use it from Cursor, Claude Desktop, VS Code Copilot, or any MCP-compatible client.

You type natural language — the assistant calls caffeine_on / caffeine_off for you.

Full documentation: docs/WIKI.md

How it works (30 seconds)

You (chat) → MCP client → caffeine-mcp → caffeine64.exe (CLI switches)

1. status — resolve CAFFEINE_EXE, check if the process is running
2. on — start Caffeine or send -appon (optional -activefor:xx)
3. off — deactivate with -appoff (process may stay in tray)
4. stop — exit with -appexit

Caffeine itself is a separate utility from Zhorn Software. This MCP does not redistribute the .exe — point CAFFEINE_EXE at your local install.

Prerequisites

| Requirement | Notes | |-------------|--------| | Node.js 18+ | Required for MCP server | | Caffeine | caffeine64.exe (or 32-bit) from Zhorn | | Windows | Uses process spawn + tasklist |

Install

Option A — npm (recommended after publish)

npm install -g @mhdd_24/caffeine-mcp

Option B — npx (no global install)

npx @mhdd_24/caffeine-mcp

Option C — clone and build (contributors)

git clone https://github.com/Mhdd-24/Caffeine-MCP.git
cd Caffeine-MCP
npm install
npm run build
node dist/index.js

Configure your MCP client

Cursor

Edit Cursor Settings → MCP or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "caffeine": {
      "command": "npx",
      "args": ["-y", "@mhdd_24/caffeine-mcp"],
      "env": {
        "CAFFEINE_EXE": "C:/Users/You/Downloads/caffeine/caffeine64.exe",
        "CAFFEINE_DEFAULT_ARGS": "-stes"
      }
    }
  }
}

After global install, you can use:

"command": "caffeine-mcp"

Local development:

"command": "node",
"args": ["C:/path/to/caffeine-mcp/dist/index.js"]

Restart Cursor (or toggle the MCP server off/on) after saving.

Environment variables

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | CAFFEINE_EXE | Yes | — | Full path to caffeine64.exe | | CAFFEINE_DEFAULT_ARGS | No | empty | Space-separated flags on every launch (e.g. -stes) |

Recommended: -stes (SetThreadExecutionState) or leave empty for classic F15 simulation.

Never commit machine-specific absolute paths. Put them only in MCP env or a local .env (gitignored).

Tools

| Tool | Purpose | |------|---------| | caffeine_status | Exe path + running processes | | caffeine_on | Start / activate keep-awake | | caffeine_off | Deactivate (-appoff) | | caffeine_toggle | Toggle active/inactive | | caffeine_stop | Exit process (-appexit) | | caffeine_run | Custom CLI args escape hatch |

Chat examples

• "Keep my PC awake"
• "Turn caffeine on for 60 minutes"
• "Is caffeine running?"
• "Stop caffeine"

What happens after npm install?

1. Package files land in node_modules/@mhdd_24/caffeine-mcp/.
2. prepack / publish includes compiled dist/.
3. The caffeine-mcp bin points to dist/index.js.
4. Your MCP client runs that entry over stdio.

After publishing to npm (maintainers)

1. Bump version in package.json and CF.SERVER.VERSION.
2. npm run build and smoke-test.
3. npm publish --access public.

Current package version: 1.0.0.

Troubleshooting

| Problem | Fix | |---------|-----| | Exe not found | Set CAFFEINE_EXE to your caffeine64.exe | | Still sleeps | Try CAFFEINE_DEFAULT_ARGS=-stes or leave empty (F15 mode) | | Stuck process | caffeine_stop or taskkill caffeine64.exe |

License

ISC (this MCP wrapper). Caffeine belongs to Zhorn Software — download separately.