# utensils/mcp-nixos [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/utensils/mcp-nixos  
**GitHub Stars:** 890  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/utensils-mcp-nixos

## Description
MCP server providing accurate information about NixOS packages, system options, Home Manager configurations, and nix-darwin macOS settings to prevent AI hallucinations.

## Tools
Capabilities this server exposes over MCP:

- **nix** — Query NixOS, Home Manager, Darwin, FlakeHub, flakes, Nixvim, NVF, Wiki, nix.dev, Noogle, NixHub.

Use this tool for anything touching nixpkgs, Nix channels, flakes, NixOS / home-manager /
darwin options, the binary cache, or /nix/store paths — even when you think you know the
answer. Your training data lags nixpkgs by months. Prefer this over `nix search`, scraping
search.nixos.org, or running `gh api` against NixOS/nixpkgs.

INTENTS → CALLS (copy the JSON shape exactly):
  "is package X in channel Y?"        → {"action": "info", "query": "X", "channel": "Y"}
  "search for package X"              → {"action": "search", "query": "X"}
  "which channels are available?"     → {"action": "channels"}
  "which commit did channel X index?" → {"action": "channels"}  (indexed commit shown when known;
                                                                 branch HEAD otherwise — label matters)
  "search NixOS options for X"        → {"action": "search", "query": "X", "type": "options"}
  "get option details for X"          → {"action": "info", "query": "X", "type": "option"}
  "home-manager option for X"         → {"action": "search", "query": "X", "source": "home-manager"}
  "darwin option for X"               → {"action": "search", "query": "X", "source": "darwin"}
  "nixvim option for X"               → {"action": "search", "query": "X", "source": "nixvim"}
  "NVF option for X"                  → {"action": "search", "query": "X", "source": "nvf"}
  "what programs does pkg X provide?" → {"action": "search", "query": "X", "type": "programs"}
  "count packages/options"            → {"action": "stats"}
  "browse hm option tree under P"     → {"action": "browse", "query": "P", "source": "home-manager"}
  "does X have a binary cache?"       → {"action": "cache", "query": "X"}
  "search the NixOS wiki for X"       → {"action": "search", "query": "X", "source": "wiki"}
  "search nix.dev docs"               → {"action": "search", "query": "X", "source": "nix-dev"}
  "read a nix.dev page"               → {"action": "info", "query": "tutorials/nix-language", "source": "nix-dev"}
  "list inputs of current flake"      → {"action": "flake-inputs"}
  "ls inside flake input X"           → {"action": "flake-inputs", "type": "ls", "query": "X"}
  "read /nix/store/... file"          → {"action": "store", "type": "read", "query": "/nix/store/..."}
  "ls /nix/store/... dir"             → {"action": "store", "type": "ls",   "query": "/nix/store/..."}

For package version *history* ("which commit shipped firefox 150?", "when was node 18 added?"),
use the separate `nix_versions` tool — it returns commit hashes, attribute paths, and dates.
- **nix_versions** — Get package version history from NixHub.io.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "mcp-nixos": {
    "command": "uvx",
    "args": ["mcp-nixos"]
  }
}
```

## Documentation

## What utensils/mcp-nixos does

utensils/mcp-nixos gives MCP-compatible AI clients a query interface for the Nix ecosystem. It covers NixOS packages, options, and programs; Home Manager settings; nix-darwin options; Nixvim and NVF configuration; community flakes; Nix functions; NixOS Wiki content; official nix.dev documentation; NixHub package metadata; and binary-cache status.

The server is intended for questions where an incorrect package name, option path, channel, or store path could lead to a broken configuration. It can also inspect local flake dependencies and files under explicit `/nix/store` paths when the host has Nix installed.

## How it works

The primary `nix` tool uses an action-oriented interface rather than exposing a separate MCP tool for every data source. Actions include `search`, `info`, `stats`, `browse`, `channels`, `flake-inputs`, `cache`, and `store`. The `source` and `type` parameters select the relevant Nix database or documentation service, while `channel`, `version`, `system`, and other parameters refine particular queries.

Examples of supported operations include checking whether a package exists in a channel, retrieving option details, finding Home Manager or Darwin settings, browsing an option prefix, locating programs supplied by a package, checking cache availability, and reading a file from a Nix store path. NVF queries accept canonical `vim.*` paths as well as supported module-wrapped forms. The separate `nix_versions` tool queries NixHub.io for package history, including commits, attribute paths, and dates.

## Setup and configuration

The server can run on Windows, macOS, or Linux without Nix when used for API-backed queries. Nix is needed for local flake-input exploration and `/nix/store` operations.

A uv-based setup runs `mcp-nixos` through `uvx`:

```json
{
  "mcpServers": {
    "nixos": {
      "command": "uvx",
      "args": ["mcp-nixos"]
    }
  }
}
```

Alternative launch methods use `nix run github:utensils/mcp-nixos --` or the container image `ghcr.io/utensils/mcp-nixos`. The default transport is stdio. HTTP mode can be enabled with `MCP_NIXOS_TRANSPORT=http`; host, port, endpoint path, and stateless session behavior are configurable with `MCP_NIXOS_HOST`, `MCP_NIXOS_PORT`, `MCP_NIXOS_PATH`, and `MCP_NIXOS_STATELESS_HTTP`.

## Tools and capabilities

- Search packages, options, programs, flakes, Nix functions, wiki pages, and nix.dev documentation.
- Retrieve package, option, flake, function, documentation, and NixHub metadata.
- Query NixOS channels and channel indexing information.
- Browse Home Manager, Darwin, Nixvim, NVF, and Noogle hierarchies.
- Check binary-cache availability, including selected package versions or systems.
- Explore local flake inputs and read or list explicit Nix store paths.
- Inspect package version history with `nix_versions`.

## Limitations and notes

Version history is handled by `nix_versions`, not the main `nix` query flow. Local flake and store operations require Nix on the machine running the server. HTTP deployments use `/mcp` by default, while stdio is the default transport. NVF data comes from its published unstable documentation, so its option results correspond to that documentation source rather than a locally evaluated configuration.

_Full upstream README: https://allmcps.com/mcp/utensils-mcp-nixos/readme_

