kern-mcp
MCP server for Linux homelabs. Inspect host resources, processes, temperatures, and systemd services, with optional llama.cpp management.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/amnotwallas--kern-mcp)HTML
<a href="/listings/amnotwallas--kern-mcp"><img src="/api/listings/amnotwallas--kern-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
On the Linux host you want to inspect, install Python 3.12+ and [uv](https://docs.astral.sh/uv/).
git clone https://github.com/amnotwallas/kern-mcp.git cd kern-mcp uv sync
**Codex CLI example.** Replace the path with the absolute path to your checkout.
codex mcp add kern-mcp -- uv --directory "/absolute/path/to/kern-mcp" run python server.py
For another MCP client, add a local stdio server with command `uv` and arguments `--directory`, `/absolute/path/to/kern-mcp`, `run`, `python`, and `server.py`.
Try asking **“How much RAM is available, and are any systemd services failing?”** Host inspection requires no Kern configuration.
flowchart LR
Client[MCP client] -->|stdio| Kern[Kern MCP]
Kern -->|Read-only inspection| Host[Linux host]
Kern -. Optional .-> Llama[Local llama.cpp]What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 118 lines
- # Kern MCP
- 
- Kern MCP is a Model Context Protocol server for Linux homelabs. Inspect host resources, processes, temperatures, and systemd services from an MCP client. If you run llama.cpp, you can also opt in to model discovery and lifecycle control.
- [Quickstart](#quickstart) · [Tools](#tools) · [llama.cpp setup](#optional-llamacpp-integration) · [Testing](#testing)
- ## Quickstart
- On the Linux host you want to inspect, install Python 3.12+ and [uv](https://docs.astral.sh/uv/).
- ```sh
- git clone https://github.com/amnotwallas/kern-mcp.git
- cd kern-mcp
- uv sync
- ```
- **Codex CLI example.** Replace the path with the absolute path to your checkout.
- ```sh
- codex mcp add kern-mcp -- uv --directory "/absolute/path/to/kern-mcp" run python server.py
- ```
- For another MCP client, add a local stdio server with command `uv` and arguments `--directory`, `/absolute/path/to/kern-mcp`, `run`, `python`, and `server.py`.
- Try asking **“How much RAM is available, and are any systemd services failing?”** Host inspection requires no Kern configuration.
- ```mermaid
- flowchart LR
- Client[MCP client] -->|stdio| Kern[Kern MCP]
- Kern -->|Read-only inspection| Host[Linux host]
- Kern -. Optional .-> Llama[Local llama.cpp]
- ```
- ## Tools
- ### Host observability
- | Tool | What it shows |
- | --- | --- |
- | `get_system_status` | Operating system, hostname, CPU, RAM, root filesystem usage, and uptime |
- | `get_processes` | Process IDs, names, CPU usage, resident memory, and start times |
- | `get_temperatures` | Linux hwmon temperatures with kernel-provided device names and sensor labels |
- | `get_systemd_services` | Runtime state of loaded services and enablement state of installed service files in `system` or `user` scope |
- `get_processes` and `get_systemd_services` accept a `limit` of 1–200 and default to 50. Service results are sorted by name, `offset` defaults to 0, and `truncated` indicates that more results follow the current page.
- ### llama.cpp tools (optional)
- | Tool | What it does |
- | --- | --- |
- | `list_llama_profiles` | List locally configured launch profiles |
- | `list_llama_models` | Discover GGUF models |
- | `list_llama_instances` | Find verified `llama-server` processes |
- | `inspect_llama_instance` | Check health and resident memory |
- | `start_llama_instance` | Start an authorized profile |
- | `stop_llama_instance` | Request a graceful stop for a verified instance |
- Set `include_runtime=true` when inspecting an instance to include cumulative process CPU time in seconds.
- Memory and disk sizes are in bytes, CPU and disk usage are percentages, uptime is in seconds, and process start times are UTC. An unavailable measurement is `null`. Process command lines and environment variables are not included.
- Linux-specific tools return an explicit status when unsupported, partially available, or unavailable. Temperature values follow the kernel hwmon millidegree-Celsius convention; unusual drivers may expose thermistor voltage instead, which the interface does not reliably identify. Service entries merge the two systemd lists by exact name: installed but unloaded units have null runtime states, and loaded units without a listed file have a null unit-file state. Templates and aliases may appear separately. Service changes between queries or pages can change results; user scope reflects the invoking user's manager and visible unit files.
- ## Optional llama.cpp integration
- > [!NOTE]
- > Host monitoring works without llama.cpp. Enable the integration only if you want to inspect or manage local inference servers.
- Use a non-root Linux account with a local `llama-server` executable and a GGUF model. Managed launches use that account’s systemd user manager.
- ### Start with a CPU profile
- The integration is disabled until you create and enable `~/.config/kern-mcp/llama.toml`. From the checkout, copy the [CPU example](examples/llama.toml.example). This command preserves an existing config.
- ```sh
- (umask 077; mkdir -p "$HOME/.config/kern-mcp" && set -C && cat examples/llama.toml.example > "$HOME/.config/kern-mcp/llama.toml")
- ```
- Edit the paths and port, then set `enabled = true`. Own the file and give it mode `0600`. Use mode `0700` for the configuration directory. Paths must be absolute, resolve without symlinks, and refer to trusted files in directories that other users cannot write to. Kern never creates or overwrites the configuration.
- ### Discover models in a directory
- Add a separate profile if you want Kern to discover models in a directory.
- ```toml
- [profiles.library]
- models_directory = "/home/user/ai/models"
- authorize_discovered_models = true
- port = 8081
- context_size = 4096
- parallel = 1
- gpu_layers = 0
- # Optional override. Use an existing, case-sensitive relative filename.
- # [profiles.library.overrides."example.gguf"]
- # context_size = 16384
- # parallel = 4
- ```
- Directory authorization covers qualifying GGUF files added later. Pass the model ID returned by `list_llama_models` when starting a directory model. Models share the profile’s port unless you override it.
- ### Use a GPU
- The examples use `gpu_layers = 0` for CPU inference. To offload layers, set a positive value and use a compatible llama.cpp build with the required drivers. Omit `device` for automatic selection or choose a name from `llama-server --list-devices`, such as `Vulkan0`, `CUDA0`, `ROCm0`, or `SYCL0`. AMD Vulkan tuning is opt-in. With a Vulkan device selected, `amd_vulkan_tuning = true` sets `RADV_PERFTEST=nogttspill` and `GGML_VK_DISABLE_HOST_VISIBLE_VIDMEM=1`.
- ### Lifecycle and permissions
- Only documented profile fields are accepted. Manual stops require `allow_manual_stop = true` and target only same-user processes running the authorized executable. Discovery is limited by process and socket permissions. Kern enforces local policy for start and stop regardless of client approval. Configure your MCP client to require approval for these operations.
- Managed servers survive MCP disconnection while the systemd user manager remains running. Without lingering, they may stop after the final user session ends. Kern does not change lingering. If a start reports an unknown outcome, inspect the returned unit before retrying.
- ## Testing
- ```sh
- make check
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.