Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/amnotwallas--kern-mcp/badge.svg)](/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

i

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
  1. # Kern MCP
  2. ![Sketch of a compact homelab rack with a terminal display and yellow Ethernet cables](assets/banner-homelab-sketch.jpg)
  3. 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.
  4. [Quickstart](#quickstart) · [Tools](#tools) · [llama.cpp setup](#optional-llamacpp-integration) · [Testing](#testing)
  5. ## Quickstart
  6. On the Linux host you want to inspect, install Python 3.12+ and [uv](https://docs.astral.sh/uv/).
  7. ```sh
  8. git clone https://github.com/amnotwallas/kern-mcp.git
  9. cd kern-mcp
  10. uv sync
  11. ```
  12. **Codex CLI example.** Replace the path with the absolute path to your checkout.
  13. ```sh
  14. codex mcp add kern-mcp -- uv --directory "/absolute/path/to/kern-mcp" run python server.py
  15. ```
  16. 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`.
  17. Try asking **“How much RAM is available, and are any systemd services failing?”** Host inspection requires no Kern configuration.
  18. ```mermaid
  19. flowchart LR
  20. Client[MCP client] -->|stdio| Kern[Kern MCP]
  21. Kern -->|Read-only inspection| Host[Linux host]
  22. Kern -. Optional .-> Llama[Local llama.cpp]
  23. ```
  24. ## Tools
  25. ### Host observability
  26. | Tool | What it shows |
  27. | --- | --- |
  28. | `get_system_status` | Operating system, hostname, CPU, RAM, root filesystem usage, and uptime |
  29. | `get_processes` | Process IDs, names, CPU usage, resident memory, and start times |
  30. | `get_temperatures` | Linux hwmon temperatures with kernel-provided device names and sensor labels |
  31. | `get_systemd_services` | Runtime state of loaded services and enablement state of installed service files in `system` or `user` scope |
  32. `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.
  33. ### llama.cpp tools (optional)
  34. | Tool | What it does |
  35. | --- | --- |
  36. | `list_llama_profiles` | List locally configured launch profiles |
  37. | `list_llama_models` | Discover GGUF models |
  38. | `list_llama_instances` | Find verified `llama-server` processes |
  39. | `inspect_llama_instance` | Check health and resident memory |
  40. | `start_llama_instance` | Start an authorized profile |
  41. | `stop_llama_instance` | Request a graceful stop for a verified instance |
  42. Set `include_runtime=true` when inspecting an instance to include cumulative process CPU time in seconds.
  43. 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.
  44. 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.
  45. ## Optional llama.cpp integration
  46. > [!NOTE]
  47. > Host monitoring works without llama.cpp. Enable the integration only if you want to inspect or manage local inference servers.
  48. 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.
  49. ### Start with a CPU profile
  50. 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.
  51. ```sh
  52. (umask 077; mkdir -p "$HOME/.config/kern-mcp" && set -C && cat examples/llama.toml.example > "$HOME/.config/kern-mcp/llama.toml")
  53. ```
  54. 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.
  55. ### Discover models in a directory
  56. Add a separate profile if you want Kern to discover models in a directory.
  57. ```toml
  58. [profiles.library]
  59. models_directory = "/home/user/ai/models"
  60. authorize_discovered_models = true
  61. port = 8081
  62. context_size = 4096
  63. parallel = 1
  64. gpu_layers = 0
  65. # Optional override. Use an existing, case-sensitive relative filename.
  66. # [profiles.library.overrides."example.gguf"]
  67. # context_size = 16384
  68. # parallel = 4
  69. ```
  70. 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.
  71. ### Use a GPU
  72. 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`.
  73. ### Lifecycle and permissions
  74. 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.
  75. 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.
  76. ## Testing
  77. ```sh
  78. make check
  79. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.