mcp-nixos

MCP-NixOS is a Model Context Protocol (MCP) server designed to provide AI assistants with accurate, real-time information about the NixOS ecosystem. It prevents LLM hallucinations by providing direct access to live data instead of relying on training data.

Key data sources provided to AI assistants:

• NixOS Packages & Options: Metadata and system configuration options.
• User Configuration: Home Manager settings and nix-darwin macOS options.
• Neovim Config: Nixvim options (via NuschtOS) and NVF options.
• Flakes: FlakeHub and community flake registries.
• Nix Functions: Signatures and documentation via Noogle.
• Community Knowledge: NixOS Wiki and nix.dev guides.
• Package Details: Version history, binary cache status (availability, size, compression), and local flake inputs read from /nix/store.

MCP-NixOS aggregates data from several authoritative Nix ecosystem sources to provide up-to-the-second information:

• Official Indices: search.nixos.org (packages & options), wiki.nixos.org (community wiki), and nix.dev (official tutorials).
• Versions & Metadata: NixHub.io (versions, store paths, licenses).
• Infrastructure: cache.nixos.org (binary cache status).
• Flakes: FlakeHub (Determinate Systems registry).
• Nix Functions & Options: noogle.dev (function signatures), NuschtOS (Nixvim options), and NVF docs (NVF option catalogue).
• Local Context: Your local /nix/store (for pinned flake inputs).

MCP-NixOS exposes two primary tools to your AI assistant. All responses are returned as plain text to ensure compatibility and ease of parsing for LLMs.

• nix: A unified query tool. Use this for searching packages, inspecting info/stats, browsing options, checking channels, looking up flake inputs, and checking binary cache status.
• nix_versions: A specialized tool for retrieving package version history and specific nixpkgs commit hashes via NixHub.io.

You can run the MCP-NixOS server inside a Docker container.

{
  "mcpServers": {
    "nixos": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"]
    }
  }
}

If you have Python installed, the recommended way to run MCP-NixOS is using uvx. This method does not install anything permanently and is ideal for most users. Add the following configuration to your MCP client settings:

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

Since Pi does not speak MCP natively, use one of these two paths:

A. pi-mcp-adapter (Recommended): Install the adapter via npm:

pi install npm:pi-mcp-adapter

Then add this to your ~/.pi/agent/mcp.json:

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

B. Project-local extension: Clone this repository. It ships .pi/extensions/mcp-nixos.ts, which is auto-loaded when running pi inside the cloned repo.

For shared setups or remote hosts, you can run the server over HTTP instead of STDIO. This allows one server instance to serve multiple clients.

Default startup (http://127.0.0.1:8000/mcp):

MCP_NIXOS_TRANSPORT=http mcp-nixos

Custom host, port, and path:

MCP_NIXOS_TRANSPORT=http \
  MCP_NIXOS_HOST=0.0.0.0 \
  MCP_NIXOS_PORT=9090 \
  MCP_NIXOS_PATH=/api/mcp \
  mcp-nixos

Stateless mode (no per-client sessions):

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

# Start with defaults: http://127.0.0.1:8000/mcp
MCP_NIXOS_TRANSPORT=http mcp-nixos

Once inside a Nix development shell, you can use the following categorized helper commands to manage the documentation site. These commands are available in both the full and docs-only shells:

• docs-install: Performs the initial npm install setup.
• docs-dev: Starts the VitePress development server with hot reload.
• docs-build: Generates a static build of the site into website/out/.
• docs-preview: Serves the built site locally for testing.
• docs-check: Runs vue-tsc to type-check Vue components.
• docs-clean: Wipes the website/out/ directory and the .vitepress/cache.

You can install the package directly using pip if you have Python installed.

pip install mcp-nixos