MCP Server: NixOS Packages, Options, Home Manager, nix-darwin

Overview

The MCP (Model Context Protocol) server for NixOS exposes live Nix-related metadata—package lists, option documentation, Home Manager modules, and nix-darwin modules—over an MCP-compatible HTTP API. By running this server on your machine or CI, AI assistants and tooling can request authoritative, up-to-date context about NixOS/Nixpkgs state and use it to generate configuration snippets, resolve package names, or validate option usage.

This project is focused on making Nix-specific data available as structured context for language models and other automation. Instead of relying on stale documentation or ad-hoc scraping, the MCP server queries the local Nixpkgs and outputs stable endpoint responses that reflect the actual versions and options present on your system or in a specified flake input.

Repository: https://github.com/utensils/mcp-nixos

Features

• Exposes Nixpkgs package metadata (names, attributes, versions).
• Serves NixOS options and option documentation for the configured channel/flake.
• Provides Home Manager module and option documentation.
• Exposes nix-darwin module/options when applicable.
• MCP-compatible HTTP API intended for consumption by LLM-based assistants and developer tools.
• Simple Nix-first installation paths: NixOS module, Home Manager package/module, nix-darwin integration, and flake runner.

Installation / Configuration

Below are common ways to install and run the MCP server. Replace example URLs/inputs with the appropriate branch or revision for reproducible results.

Using flakes (run locally)

# Run the MCP server directly from the flake
nix run github:utensils/mcp-nixos#mcp-server

Enable as a NixOS system service (flakes-enabled configuration)

# /etc/nixos/configuration.nix (flakes)
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs";
    mcp-nixos.url = "github:utensils/mcp-nixos";
  };

  imports = [ inputs.mcp-nixos.nixosModule ];

  services.mcp-nixos = {
    enable = true;
    bindAddress = "127.0.0.1";
    port = 9188;
    # additional options such as access controls may be available
  };
}

Home Manager integration (home.nix, flakes)

# home.nix (flakes)
{ inputs, ... }:
{
  imports = [ inputs.mcp-nixos.homeManagerModule ];

  programs.mcp-nixos = {
    enable = true;
    # configure extra options if exposed
  };
}

Install on macOS with nix-darwin (example)

# darwin-configuration.nix / flake.darwinConfigurations
{
  imports = [ inputs.mcp-nixos.nixDarwinModule ];

  services.mcp-nixos.enable = true;
  services.mcp-nixos.port = 9188;
}

Note: If you prefer not to use flakes, fetch the repository archive and import the included NixOS/Home Manager/nix-darwin modules in the usual way.

Available Resources

The MCP server exposes structured endpoints that map to common Nix resources. Exact paths may depend on server version; examples below are typical:

Example curl query

curl "http://127.0.0.1:9188/mcp/v1/packages?query=python" | jq

Responses are JSON suitable for downstream consumption by tooling and LLM context feeders.

Use Cases

• AI-assisted configuration authoring
  • An assistant can query /options to fetch the exact documentation for networking.nat.enable and insert a correct NixOS option into a config.
• Accurate package resolution
  • Rather than guessing attribute names (e.g., python3 vs. python39), an assistant queries /packages to find the attribute path and version before generating a derivation or configuration.
• Home Manager migration and