<p align="center">
  <img src="icon.png" width="120" alt="PCCheck logo">
</p>

<h1 align="center">🩺 PCCheck — let Claude actually check your PC</h1>

<p align="center">
  <!-- CI badge goes live once .github/workflows-pending/ci.yml is activated (see PUBLISH.md):
  <a href="https://github.com/jjackk0k/pccheck-mcp/actions/workflows/ci.yml"><img src="https://github.com/jjackk0k/pccheck-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> -->
  <img src="https://img.shields.io/badge/tools-100%25%20read--only-2ea44f" alt="100% read-only">
  <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen" alt="node >= 18">
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license">
</p>

**Ask Claude "why is my PC slow?" and get a real answer — not generic advice.**

PCCheck is an MCP server that gives Claude read-only eyes into your computer: hardware specs, live CPU/GPU/RAM load, temperatures, disk space hogs, startup bloat, crash history, wifi quality, and a real speed test. Claude stops guessing and starts diagnosing.

<!-- DEMO GIF GOES HERE — 15-25s: type "why is my PC slow?", tool calls fire, verdict appears. See PUBLISH.md. -->

> 🧑‍⚕️ *"Your GPU is fine and your CPU is idling — but Chrome is holding 9GB of RAM, your C: drive is 96% full, and there's a 20GB VM image in Downloads you probably forgot about. Delete that and you'll feel the difference."*
> — the kind of answer this unlocks

## What you can ask

- 🔍 **"Run a full checkup on my PC"**
- 🐌 "Why is my computer so slow *right now*?"
- 📉 "My PC got slower lately — what changed?"
- 💾 "What's eating my disk space?"
- 🎮 "Can my PC run Cyberpunk 2077 at 1440p?" / "Why does my game stutter?"
- 💥 "Why did my PC crash yesterday?"
- 📶 "Is my wifi the problem, or my internet provider?"
- ⚡ "How fast is my internet actually?"
- 🔥 "Is my PC running too hot?"
- 🧹 "Roast my startup programs."
- 🔋 "Should I replace my laptop battery?"

## What you need

The **Claude Desktop app** (Windows or Mac — the free plan works) or **Claude Code**. The claude.ai website and the mobile app can't run local extensions — they can't see your PC.

PCCheck is **Windows-first** (crash logs, antivirus status, startup toggles are Windows-only for now); specs, performance, disk, network, and speed checks also work on macOS and Linux.

## Install

### Option 1 — Claude Desktop, one click (recommended)

1. Download `pccheck.mcpb` from the [latest release](https://github.com/jjackk0k/pccheck-mcp/releases/latest)
2. Double-click it (or drag into Claude Desktop → Settings → Extensions)
3. Click **Install**. No terminal, no Node.js, nothing else.

**Check it worked:** ask Claude *"run a full checkup on my PC."* The first time, Claude will ask permission for each tool — click Allow. (PCCheck also adds one-click prompts to Claude Desktop's **+** menu: *Full PC checkup*, *Why is my PC slow?*, *Free up disk space*.)

### Option 2 — Claude Code (one command)

```bash
claude mcp add pccheck -- npx -y pccheck-mcp
```

### Option 3 — any MCP client (manual config)

```json
{
  "mcpServers": {
    "pccheck": {
      "command": "npx",
      "args": ["-y", "pccheck-mcp"]
    }
  }
}
```

On Windows, if your client needs it: `"command": "cmd", "args": ["/c", "npx", "-y", "pccheck-mcp"]`.

> **Note:** npx install requires the package on npm — until `pccheck-mcp` is published there, use the `.mcpb` release file (Option 1) or clone + `npm run build` + point your config at `dist/index.js`.

## What Claude sees (15 tools)

| Tool | Answers | Platforms |
|---|---|---|
| `full_checkup` | "Check my PC" — everything below in one call, ~20s | all |
| `system_overview` | "What are my specs?" / "Can I run this game?" | all |
| `performance_snapshot` | "Why is it slow right now?" — live load + top processes | all |
| `top_processes` | "How much is Chrome using?" | all |
| `gpu_info` | GPU model, VRAM, driver, live utilization, display refresh rates | all (live stats: NVIDIA) |
| `temperatures` | "Is it running hot?" — CPU/GPU temps + healthy ranges | all (best on NVIDIA) |
| `disk_space` | Drive fullness + SSD/HDD health (SMART) | all |
| `scan_folder_sizes` | "What's eating my disk?" — ranks folders by size | all |
| `startup_programs` | Boot bloat, including which items are actually enabled | Windows (basic on Mac/Linux) |
| `network_check` | Router vs internet pings — "bad wifi" vs "bad ISP" (latency & loss) | all |
| `speed_test` | "How fast is my internet?" — actual download Mbps | all |
| `what_changed` | "It got slower recently" — diff vs the last checkup | all |
| `crash_report` | Blue screens, freezes, app crashes, antivirus, pending reboots | Windows |
| `installed_software` | Biggest / most recent installs — find the bloat | Windows (names-only on Mac) |
| `battery_health` | Wear level, cycle count, charge state | all |

## Privacy & safety — read this, it's honest

- **Read-only by design.** No tool can change, delete, install, or configure anything on your system. The worst PCCheck can do is *look*. The single exception to "writes nothing": `what_changed` keeps one snapshot file in `~/.pccheck` so it can tell you what changed later — delete it anytime. (~1,500 lines of TypeScript, 3 runtime dependencies — auditable in one sitting.)
- **PCCheck itself sends nothing about you anywhere.** No telemetry, no accounts, no external APIs. Its only network activity: the latency test in `network_check` (standard pings to your router, `1.1.1.1`, `8.8.8.8`) and `speed_test`, which *downloads* throwaway data from Cloudflare's public speed endpoint — nothing is uploaded.
- **But be clear about how MCP works:** results Claude asks for become part of your Claude conversation, which is processed by Anthropic like anything else you type. Depending on what you ask, that can include:

  | If Claude calls… | Your conversation will contain… |
  |---|---|
  | `system_overview` | PC model, hostname, hardware specs |
  | `scan_folder_sizes` | folder/file names (incl. your Windows username in paths) |
  | `installed_software` | names of installed programs |
  | `network_check` | your wifi network name (SSID) |
  | `crash_report` | crash-log excerpts |

  Don't want something seen? Don't ask about it — tools only run when Claude calls them for your request, and you can see every call in the chat.
- **No admin rights needed.** Everything works as a normal user (Windows hides CPU temperature from non-admin processes — GPU temp still works).
- File and program names on your disk are treated as data, not instructions — but as with anything an AI reads, weirdly-named files could try to influence the conversation. Read-only design caps the blast radius.

## FAQ

**Can it delete/change/"fix" things itself?** No. Every tool is read-only by design — Claude diagnoses and tells you how to fix things yourself. That's a feature, not a limitation.

**Does it work on claude.ai in my browser?** No — local extensions need the Claude Desktop app or Claude Code.

**Does the free Claude plan work?** Yes.

**Mac/Linux?** Yes for specs, performance, disk, network, speed test, battery. Crash logs, antivirus, and startup-toggle detail are Windows-only right now.

**How do I uninstall?** Claude Desktop: Settings → Extensions → PCCheck → Remove. Claude Code: `claude mcp remove pccheck`.

## Troubleshooting

- **"CPU temperature unavailable"** — Windows blocks this for non-admin processes; it's expected. GPU temperature (NVIDIA) still works.
- **Claude doesn't show the tools** — fully quit Claude Desktop (system tray → Quit) and reopen; extensions load at startup.
- **`npx` install fails on Windows** — use the `cmd /c` variant shown above, or the `.mcpb` file which needs no Node at all.
- **A scan times out** — every tool is time-boxed on purpose; ask Claude to try again with a smaller scope (a subfolder instead of all of `C:\`) or a longer time budget.

## Development

```bash
git clone https://github.com/jjackk0k/pccheck-mcp
cd pccheck-mcp
npm install
npm run build
npm run smoke   # exercises all 15 tools over real stdio JSON-RPC
```

CI runs the same smoke suite on Windows and Linux runners for every push.

## Roadmap

- Deeper macOS/Linux parity (startup items, installed apps with sizes)
- Optional LibreHardwareMonitor bridge for full sensor data (CPU temp without admin)
- "What changed since yesterday?" snapshot diffing

## License

MIT — see [LICENSE](LICENSE).

---

*Built for the person whose family asks them to fix the computer. Now Claude can be that person.*