MCP-NixOS

MCP-NixOS is an MCP server that provides AI assistants with real-time access to Nix and NixOS ecosystems, eliminating hallucinations of package names and configuration options. It connects directly to multiple external registries and documentation indices, including NixOS packages and options, Home Manager, nix-darwin, Nixvim, NVF, FlakeHub, Noogle function signatures, the NixOS Wiki, nix.dev, and NixHub version histories. Developers, system administrators, and DevOps engineers managing Nix-based systems use this tool to query live configuration schemas, verify package availability, and check binary cache status directly within AI-assisted workflows. The server operates without requiring a local Nix installation for network queries, running anywhere Python can execute, while optionally exposing tools to inspect local flake inputs and Nix store paths when running on a host with Nix installed. By compressing search and lookup capabilities into two unified tools, the server minimizes context window consumption while enabling language models to generate accurate Nix expressions, validate module configurations, inspect flake dependency graphs, and retrieve historical commit hashes for reproducible builds.

Category: Developer Tools & Code Intelligence

Tags: darwin, home-manager, nix, nixos, package-management

Visit MCP-NixOS

How to install and configure MCP-NixOS

1. Ensure an MCP-compatible client like Claude Desktop or Cursor is installed. 2. To run the server using uvx without installing Nix, add the following entry to the mcpServers object in your client configuration: json { "mcpServers": { "nixos": { "command": "uvx", "args": ["mcp-nixos"] } } } 3. Alternatively, if Nix is installed on your host, register the server via nix run: json { "mcpServers": { "nixos": { "command": "nix", "args": ["run", "github:utensils/mcp-nixos", "--"] } } } 4. For Docker environments, register using the container image: json { "mcpServers": { "nixos": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"] } } } 5. Save the configuration and restart your MCP client to enable the server.

What you can do with MCP-NixOS

• Looking up exact package names, attribute paths, and binary cache availability on cache.nixos.org across stable or unstable NixOS channels. - Inspecting configuration option schemas and defaults for Home Manager, nix-darwin, Nixvim, or NVF modules when building custom system configurations. - Retrieving Nix language standard library function signatures, documentation, and parameter definitions from Noogle directly inside an AI prompt. - Locating historical package versions and specific nixpkgs commit hashes through NixHub to lock reproducible package definitions in Nix expressions. - Browsing local flake dependencies and reading configuration files directly from the Nix store path when managing local flake setups.

Key facts

• Open Source
• https://github.com/utensils/mcp-nixos
• Developer Tools & Code Intelligence, Web Search & Research
• darwin, home-manager, nix, nixos, package-management

Part of MCP Servers

Do I need Nix installed to use MCP-NixOS?

No, a local Nix installation is not required for standard queries. The server queries web APIs such as search.nixos.org, FlakeHub, and NixHub over the network, allowing it to run on Linux, macOS, or Windows environments. Local Nix is only required for exploring local flake inputs or inspecting files directly in /nix/store.

What tools does MCP-NixOS provide to the AI model?

MCP-NixOS consolidates its capabilities into two tools: nix and nix_versions. The nix tool handles searching, browsing, and inspecting metadata for packages, options, flakes, documentation, and caches across multiple sources. The nix_versions tool queries historical package versions, platform availability, and nixpkgs commit hashes for reproducible pinning.

Which documentation sources does MCP-NixOS query?

The server accesses NixOS packages and options, Home Manager, nix-darwin, Nixvim, NVF Neovim options, FlakeHub flakes, Noogle Nix library functions, the official NixOS Wiki, nix.dev guides, and NixHub metadata. This breadth ensures AI agents reference authoritative, up-to-date documentation rather than guessing configuration paths.

How can I run MCP-NixOS over HTTP?

You can run MCP-NixOS over HTTP by setting the environment variables MCP_NIXOS_TRANSPORT to http, MCP_NIXOS_HOST, and MCP_NIXOS_PORT before executing mcp-nixos. The server exposes an MCP endpoint at /mcp by default, and can also run in stateless HTTP mode when MCP_NIXOS_STATELESS_HTTP is enabled.

Is MCP-NixOS open source?

Yes, MCP-NixOS is an open-source project hosted on GitHub under the utensils organization. It can be installed directly from PyPI, run using uvx or Docker, or consumed declaratively as a Nix package in NixOS, Home Manager, or nix-darwin configurations.