LABSCO SUMMARY

It stops the model handing you an option name that does not exist.

Nix configuration fails in confusing ways when an attribute is nearly right, and a model trained on an older nixpkgs is a reliable source of nearly-right. Two tools cover eleven sources deliberately — the whole surface is small enough to keep loaded, and the names it returns come from the live channels rather than memory.

What it is

Two tools against the Nix ecosystem's own sources: one queries NixOS, Home Manager, nix-darwin, flakes, FlakeHub, Nixvim, NVF, the Wiki, nix.dev, Noogle and NixHub; the other returns a package's version history from NixHub. It queries public APIs, so the machine running it does not need Nix installed.

What you get

Packages, options and programs searched across NixOS, Home Manager and nix-darwin, scoped by channel, type and result count
One package or option read in detail, rather than skimmed from a search result
Option trees browsed by prefix — Home Manager, Darwin, Nixvim, NVF and Noogle — which is how you find the setting whose exact name you do not know
Community flakes and the FlakeHub registry searched from the same call
Nix function signatures from Noogle, wiki articles from wiki.nixos.org, and the official guides on nix.dev
The available NixOS channels listed, and counts and categories when you want to know how big a search space is
Binary cache status from cache.nixos.org, with download sizes, so you know whether a package will be fetched or built
Local flake inputs read out of the Nix store, for the one case that does need Nix on the machine
A package's version history from NixHub, with the commit hash behind each version, filterable to the one version you care about

Requirements

Python 3.11 or newer with uv — no account and no key, and no NixOS: it works on Windows and macOS too, because everything is a query against public APIs. A Nix flake and a container image are published as alternatives, and MCP_NIXOS_TRANSPORT=http turns it into a remote server on a host and port you choose. MIT licensed.

Setup effort

One command — uvx mcp-nixos

See installation options

USE CASES

01

Writing a configuration.nix entry that will actually evaluate

Search the option by keyword, then read its full description, type and default before writing it in.

nix

02

Finding the setting when you only know roughly where it lives

Browse the option tree by prefix — Home Manager, Darwin or Nixvim — instead of guessing at the leaf name.

nix

03

Pinning a package to the version you need

Read its version history with the commit behind each release, then pin to that commit.

nix_versionsnix

04

Knowing whether a build will take an hour

Check the binary cache for the package first — the download size tells you it is cached, the absence tells you it will compile.

nix

05

Understanding a Nix function you have not used

Look up its signature and documentation on Noogle, or find the guide covering it on nix.dev and the wiki.

nix

2 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`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.

Notes:

To search NixOS *options*, use action=search with type=options. Do NOT use action=browse for source=nixos — browse is for walking a pre-indexed option tree and only works with home-manager, darwin, nixvim, nvf, or noogle.
For source=nvf, canonical option paths are vim.*. The shorthand programs.nvf.vim.* and NixOS/Home Manager module path programs.nvf.settings.vim.* are normalized automatically.
For source=nix-dev, action=info returns the page markdown. The query may be a bare docname like "tutorials/nix-language", the URL printed by nix-dev search ("https://nix.dev/tutorials/nix-language"), or a rendered ".html" URL.
action=info for packages matches on the exact attribute path first, then the exact pname. If multiple packages share a pname (e.g. firefox / firefox-esr / firefox-mobile), the canonical attribute wins and the response flags the disambiguation explicitly.
Omit parameters you don't need; do not pass empty strings for optional args.

BEFORE YOU INSTALL

What to know first

Tools you get

2 tools when we connected.

Requires

uvx on PATH

Where it runs

The documented client runs the server on your machine.

CONTEXT COST

Light Standing cost

Rated by the size of the 2 tool definitions that ride along on every turn, not by how many there are

INSTALLATION

Connect your client

Server setup

TERMINAL

uvx mcp-nixos

MCP Clients

Pi Coding Agent

PI CODING AGENT · JSON

{
  "mcpServers": {
    "nixos": {
      "command": "uvx",
      "args": [
        "mcp-nixos"
      ],
      "lifecycle": "lazy"
    }
  }
}

NixOS MCP

It stops the model handing you an option name that does not exist.

What it is

What you get

Requirements

Setup effort

Writing a configuration.nix entry that will actually evaluate

Finding the setting when you only know roughly where it lives

Pinning a package to the version you need

Knowing whether a build will take an hour

Understanding a Nix function you have not used

2 tools

`nix`

`nix_versions`

What to know first

Tools you get

Requires

Where it runs

Light Standing cost

Connect your client

Server setup

MCP Clients

Pi Coding Agent

NixOS MCP

It stops the model handing you an option name that does not exist.

What it is

What you get

Requirements

Setup effort

Writing a configuration.nix entry that will actually evaluate

Finding the setting when you only know roughly where it lives

Pinning a package to the version you need

Knowing whether a build will take an hour

Understanding a Nix function you have not used

2 tools

nix

nix_versions

What to know first

Tools you get

Requires

Where it runs

Light Standing cost

Connect your client

Server setup

MCP Clients

Pi Coding Agent

Same category

Criage MCP Server

Socket

Arch MCP

Security Audit Tool

`nix`

`nix_versions`