# sysmcp

MCP server that exposes live host signal — CPU, memory, processes, network —
to Cursor / Claude. Default path is `/proc` (no root). Optional eBPF tools
activate when `CAP_BPF` / `CAP_PERFMON` is available.

**Repo:** https://github.com/arunmm8335/sysmcp · **Version:** 0.5.0

## Tools

| Tool | What it returns |
|------|-----------------|
| `host_dashboard` | Full snapshot (CPU, mem, top procs, listeners, eBPF) |
| `poll_host_stats` | Lightweight CPU/mem/process snapshot for auto-refresh |
| `system_stats` | CPU %, memory %, load averages, NIC rx/tx B/s |
| `top_processes` | Top PIDs by **CPU % over a sample window**, plus `skipped_count` |
| `network_connections` | IPv4+IPv6 TCP/UDP; filters + `resolve_pid`; row limit (default 200) |
| `cgroup_cpu` | Top cgroups by CPU % (cgroup v2 `cpu.stat`) |
| `iface_rates` | Per-interface byte/packet rates (`/proc/net/dev`) |
| `ebpf_status` | Whether eBPF works; includes `how_to_enable` when not |
| `ebpf_activity` | Fork + `sched_switch` rates via eBPF, or `available: false` |
| `ebpf_traffic` | Kernel RX/TX packet rates (`netif_receive_skb` / `net_dev_xmit`) |

True per-connection byte counters need sock-level eBPF; `iface_rates` +
`ebpf_traffic` are the practical deeper network signal today.

## Browser dashboard (HTTP)

```bash
go build -o sysmcp ./cmd/sysmcp
./sysmcp serve
# open http://127.0.0.1:8787/
```

Optional: `./sysmcp serve -addr 127.0.0.1:9000`

APIs: `/api/dashboard`, `/api/poll` (JSON).

## Interactive views in Cursor

Ask *“Open the host dashboard”* / *“Refresh the host dashboard”*. The agent
calls `host_dashboard` and opens a **Cursor Canvas** beside the chat.

MCP Apps resource `ui://sysmcp/dashboard` remains for hosts that render Apps
iframes. Cursor often uses Canvas + JSON instead.

### `network_connections` filters

| Arg | Effect |
|-----|--------|
| `listen_only` | TCP `LISTEN` + unbound UDP |
| `protocol` | `tcp` / `udp` |
| `family` | `ipv4` / `ipv6` |
| `state` | e.g. `ESTABLISHED`, `LISTEN` |
| `local_port` | filter by local port |
| `pid` | owning PID (implies `resolve_pid`) |
| `limit` | max rows (default 200, max 1000); `truncated` in result |

## Install

**Release binaries** (linux amd64 / arm64) ship on each `v*` tag:

https://github.com/arunmm8335/sysmcp/releases

```bash
# example amd64
curl -fsSL -o sysmcp.tgz \
  https://github.com/arunmm8335/sysmcp/releases/download/v0.5.0/sysmcp_0.5.0_linux_amd64.tar.gz
tar -xzf sysmcp.tgz
```

Or from source:

```bash
go install github.com/arunmm8335/sysmcp/cmd/sysmcp@latest
# or
git clone https://github.com/arunmm8335/sysmcp.git
cd sysmcp
go build -o sysmcp ./cmd/sysmcp
```

### MCP Registry (one-click)

Namespace: `io.github.arunmm8335/sysmcp`. Tag releases build `.mcpb` assets and
attempt an OIDC publish via `mcp-publisher`. To publish manually after a
release (recommended if OIDC is not set up):

```bash
# fill fileSha256 in server.json from the release *.mcpb.sha256 files, then:
curl -fsSL -o mcp-publisher.tgz \
  https://github.com/modelcontextprotocol/registry/releases/download/v1.8.0/mcp-publisher_linux_amd64.tar.gz
tar -xzf mcp-publisher.tgz mcp-publisher
./mcp-publisher login github
./mcp-publisher publish ./server.json
```

See https://modelcontextprotocol.io/registry/quickstart

## Cursor / Claude MCP config

```json
{
  "mcpServers": {
    "sysmcp": {
      "command": "/absolute/path/to/sysmcp"
    }
  }
}
```

## Enable eBPF (optional)

```bash
go build -o sysmcp ./cmd/sysmcp
./scripts/grant-caps.sh ./sysmcp
# sets: cap_bpf,cap_perfmon+ep
```

Restart the MCP server after granting caps. Without caps, eBPF tools return
`available: false` — `/proc` tools still work.

## Demo

```bash
go test ./... -count=1
go build -o sysmcp ./cmd/sysmcp
go run ./scripts/smoke.go ./sysmcp
./sysmcp serve   # then open http://127.0.0.1:8787/
```

## License

MIT