MCP-NixOS - Because Your AI Shouldn't Hallucinate Package Names

CodeRabbit Pull Request Reviews

Quick Start

🚨 No Nix/NixOS Required! Works on any system - Windows, macOS, Linux. You're just querying APIs.

Option 1: uvx (Recommended)

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

Option 2: Nix

{
  "mcpServers": {
    "nixos": {
      "command": "nix",
      "args": ["run", "github:utensils/mcp-nixos", "--"]
    }
  }
}

Option 3: Docker

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

Your AI now has access to real NixOS data instead of making things up. You're welcome.

What Is This?

An MCP server providing accurate, real-time information about:

NixOS packages - 130K+ packages that actually exist
NixOS options - 23K+ ways to configure your system
Home Manager - 5K+ options for dotfile enthusiasts
nix-darwin - 1K+ macOS settings Apple doesn't document
Nixvim - 5K+ options for Neovim configuration via NuschtOS search
FlakeHub - 600+ flakes from FlakeHub.com registry
Package versions - Historical versions with commit hashes via NixHub.io

The Tools

Just two. We consolidated 17 tools into 2 because your AI's context window isn't infinite.

~365 tokens total. That's it. While other MCP servers are hogging your context like it's Black Friday, we're sipping minimalist tea in the corner. Your AI gets NixOS superpowers without the bloat.

`nix` - Unified Query Tool

One tool to rule them all:

nix(action, query, source, type, channel, limit)

Action	What it does
`search`	Search packages, options, programs, or flakes
`info`	Get detailed info about a package or option
`stats`	Get counts and categories
`options`	Browse Home Manager/Darwin options by prefix
`channels`	List available NixOS channels

Source	What it queries
`nixos`	Packages, options, programs
`home-manager`	Home Manager options
`darwin`	nix-darwin options
`flakes`	Community flakes (search.nixos.org)
`flakehub`	FlakeHub registry (flakehub.com)
`nixvim`	Nixvim Neovim configuration options

Examples:

# Search NixOS packages
nix(action="search", query="firefox", source="nixos", type="packages")

# Get package info
nix(action="info", query="firefox", source="nixos", type="package")

# Search Home Manager options
nix(action="search", query="git", source="home-manager")

# Browse darwin options
nix(action="options", source="darwin", query="system.defaults")

# Search Nixvim options
nix(action="search", query="telescope", source="nixvim")

# Get Nixvim option info
nix(action="info", query="plugins.telescope.enable", source="nixvim")

# Search FlakeHub
nix(action="search", query="nixpkgs", source="flakehub")

# Get FlakeHub flake info
nix(action="info", query="NixOS/nixpkgs", source="flakehub")

# Get stats
nix(action="stats", source="nixos", channel="stable")

`nix_versions` - Package Version History

Find historical versions with nixpkgs commit hashes:

nix_versions(package, version, limit)

Examples:

# List recent versions
nix_versions(package="python", limit=5)

# Find specific version
nix_versions(package="nodejs", version="20.0.0")

Installation

You DON'T need Nix installed. This runs anywhere Python runs.

# Run directly (no install)
uvx mcp-nixos

# Or install
pip install mcp-nixos

For Nix users:

nix run github:utensils/mcp-nixos
nix profile install github:utensils/mcp-nixos

Development

nix develop          # Enter dev shell
nix build            # Build package
pytest tests/        # Run tests
ruff check .         # Lint
ruff format .        # Format
mypy mcp_nixos/      # Type check

Acknowledgments

NixHub.io - Package version history
search.nixos.org - Official NixOS search
FlakeHub - Flake registry by Determinate Systems
Jetify - Creators of Devbox and NixHub
NuschtOS - Static option search infrastructure powering Nixvim support
Nixvim - Neovim configuration framework for Nix

License

MIT - Because sharing is caring.

Created by James Brink. Maintained by mass̶o̶c̶h̶i̶s̶t̶s̶ enthusiasts who enjoy Nix.

mcp-nixos