Content
# Ctrl Vitals
A lightweight system monitor and MCP server for Linux. Built with Rust + GTK4 — ~740KB binary, zero bloat.
Dual mode: launch the GUI widget, or use the MCP server to give AI agents real-time system stats.
## Features
- **CPU** per-core usage, aggregate sparkline (2min), temperature
- **GPU** core util, VRAM, temperature (NVIDIA)
- **RAM** used/total with sparkline
- **Disk** root partition usage
- **Network** real-time up/down speed
- **Top processes** by CPU
- **Draggable & resizable** window
- **MCP server** — stdin/stdout JSON-RPC for AI agents
## MCP Server for AI Agents
Ctrl Vitals doubles as an [MCP](https://modelcontextprotocol.io) server. AI agents (Claude Desktop, Cline, Cursor, etc.) can query real-time hardware stats without any daemon, HTTP port, or configuration.
### Tools exposed
| Tool | Returns |
|------|---------|
| `get_cpu_usage` | Per-core + aggregate usage %, temperature, core count |
| `get_gpu_stats` | GPU core %, VRAM used/total, temperature |
| `get_ram_stats` | RAM used/total GB, percentage |
| `get_disk_stats` | Disk usage for a mount point (default `/`) |
| `get_network_speed` | Real-time download/upload with interface name |
| `get_top_processes` | Top N processes by CPU (default 5) |
### Usage with AI agents
**Claude Desktop / Cline / any MCP client:**
Add to your MCP config (`~/.config/opencode/mcp.json` or `claude_desktop_config.json`):
```json
{
"mcpServers": {
"ctrl-vitals": {
"command": "ctrl-vitals",
"args": ["mcp"]
}
}
}
```
Then in your AI agent prompt:
> "What's my current CPU and RAM usage?"
> "Show me the top 5 processes by CPU"
> "How much disk space is free?"
The agent will call the corresponding tools and respond with live data.
### Test manually
```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ctrl-vitals mcp
# Get CPU usage (takes ~200ms for a fresh sample)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_cpu_usage","arguments":{}}}' | ctrl-vitals mcp
# Get RAM stats
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_ram_stats","arguments":{}}}' | ctrl-vitals mcp
```
## Install
### From release
```bash
# tar.gz
tar xzf ctrl-vitals-v0.2.0-linux-x86_64.tar.gz
./install.sh # user install (~/.local/bin)
# or
sudo ./install.sh --system # system-wide (/usr/local/bin)
# .deb
sudo dpkg -i ctrl-vitals_0.2.0_amd64.deb
```
Both methods install `ctrl-vitals` to your PATH. The MCP server and GUI widget are the **same binary** — just use `ctrl-vitals mcp` for the server or `ctrl-vitals` for the GUI.
### From source
```bash
sudo apt install libgtk-4-dev # Ubuntu/Debian
# or
sudo dnf install gtk4-devel # Fedora
cargo install --git https://github.com/YOUR_USER/ctrl-vitals
```
## Usage
```bash
ctrl-vitals # Launch GUI widget
ctrl-vitals mcp # Start MCP server (stdin/stdout)
```
### GUI controls
- **Drag** anywhere on the window to move it
- **Resize** by dragging the edges
- **Close** with Ctrl+C in the terminal
## Uninstall
**If installed via .deb:**
```bash
sudo dpkg -r ctrl-vitals
```
**If installed via `install.sh --system`:**
```bash
sudo rm /usr/local/bin/ctrl-vitals /usr/local/share/applications/ctrl-vitals.desktop
```
**If installed via `install.sh` (user):**
```bash
rm ~/.local/bin/ctrl-vitals ~/.local/share/applications/ctrl-vitals.desktop
```
**If installed via `cargo install`:**
```bash
cargo uninstall ctrl-vitals
```
## Requirements
- Linux x86_64 with X11 or Wayland
- GTK 4.14+ (preinstalled on Ubuntu 24.04+, Fedora 39+) — only needed for GUI
- NVIDIA GPU with `nvidia-smi` for GPU stats (optional)
## Build Dependencies
| Package | Ubuntu/Debian | Fedora |
|---------|---------------|--------|
| GTK4 dev | `libgtk-4-dev` | `gtk4-devel` |
| Rust | `rustc cargo` | `rust cargo` |
## License
MIT
