mcp-nixos

MCP-NixOS provides real-time, accurate information about NixOS packages, options, and related tooling via a lightweight MCP server. It exposes a single, unified querying tool named nix that you can call to search, fetch details, and explore data sources like nixos packages, Home Manager options, darwin options, and more. The server is optimized to minimize context usage while offering a broad set of query capabilities across multiple sources, including packages, options, flakes, and official documentation.

To use it, run the server with the uvx (recommended) method described in the installation notes, then issue calls to the nix tool with actions such as search, info, or options. For example, you can search for a package like firefox, retrieve detailed package or option info, or browse Home Manager options by prefix. The tool supports numerous sources (nixos, home-manager, darwin, nixvim, wiki, nix-dev, noogle, flakehub, nixhub, etc.) enabling you to discover data across the Nix ecosystem from a single interface. Advanced features include querying flake inputs, checking binary cache status, and listing channels. The combination of actions and sources lets you quickly assemble precise queries such as: how to find a specific NixOS package, what options exist for a given Home Manager module, or what the available channels are for a given nixos configuration.

Prerequisites:\n- Python 3.11+ (and pip) installed on your system.\n- Internet access to pull dependencies.\n\nOption A: Install via uvx (recommended)\n1) Install uvx if you don’t have it:\nbash\npipx install uvx # or your preferred installation method for uvx\n 2) Run the MCP server:\nbash\nuvx mcp-nixos\n 3) Verify the server is running and listening on the default MCP endpoint. You can connect via the mcp client tooling or your HTTP transport as configured.\n\nOption B: Docker (alternative)\n1) Ensure Docker is installed and running.\n2) Run the MCP server container:\nbash\ndocker run --rm -i ghcr.io/utensils/mcp-nixos\n\n3) Connect to the container’s MCP endpoint as documented in the README.\n\nOption C: Nix (alternative)\n1) Ensure Nix is installed.\n2) Run the MCP server directly using the Nix channel, following the config example in the README.\n\nNotes:\n- The server is designed to work across platforms (Windows, macOS, Linux) by querying NixOS data sources at runtime.\n- If using HTTP transport, set MCP_NIXOS_TRANSPORT and related environment variables as needed.\n\nPrerequisites recap: Python 3.11+, uvx or Docker or Nix, and network access to fetch data sources.

Tips and common issues:\n- If you encounter missing data, ensure your environment has network access to NixOS data sources (Nix official docs, caches, and the various repositories listed in the README).\n- When using the HTTP transport, remember you can enable stateless HTTP mode with MCP_NIXOS_STATELESS_HTTP=1 to avoid per-client session state.\n- To tailor results, leverage the source and action combinations supported by nix, e.g., nix(action="search", query="firefox", source="nixos") or nix(action="info", query="lib.attrsets.mapAttrs", source="noogle").\n- For local development or debugging, running with STDIO transport is simplest and avoids HTTP networking.\n- The NixOS data sources include NixOS Wiki, FlakeHub, Nixvim, and Home Manager options, so you can explore a wide range of topics from package metadata to configuration options.\n- If you plan to deploy in a CI environment, pin the version of the MCP server or container to ensure reproducible behavior.