Skip to main content
Glama

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

MCP Toplist

CI codecov PyPI FlakeHub Python 3.11+ CodeRabbit Pull Request Reviews Built with Claude

Quick Start

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

Install MCP Server

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

Option 2: Nix

Install MCP Server

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

Option 3: Docker

Install MCP Server

{
  "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.

Option 4: HTTP (Remote MCP)

FastMCP supports running this server over HTTP at a URL (the MCP endpoint defaults to /mcp).

# Run an HTTP MCP server at http://127.0.0.1:8000/mcp
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_HOST=127.0.0.1 MCP_NIXOS_PORT=8000 mcp-nixos

STDIO (default):

MCP_NIXOS_TRANSPORT=stdio mcp-nixos

Custom path:

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixos

Stateless HTTP (disables per-client session state):

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

Option 5: Pi Coding Agent

Pi does not speak MCP natively. Two supported paths:

A. pi-mcp-adapter (recommended — speaks MCP, single source of truth):

pi install npm:pi-mcp-adapter

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

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

B. Project-local extension (clone + run): this repo ships .pi/extensions/mcp-nixos.ts, auto-loaded when you run pi in the cloned repo. Optional: cd .pi && npm install for editor type resolution. Pi runs it either way.

Related MCP server: Grounded Code MCP

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

  • NVF - 2.4K+ Neovim options from its published unstable documentation

  • FlakeHub - 600+ flakes from FlakeHub.com registry

  • Noogle - 2K+ Nix functions with type signatures via noogle.dev

  • NixOS Wiki - Community documentation and guides from wiki.nixos.org

  • nix.dev - Official Nix tutorials and guides from nix.dev

  • Package versions - Historical versions with commit hashes via NixHub.io

  • Binary cache status - Check if packages are cached on cache.nixos.org with download sizes

  • Local flake inputs - Explore your pinned flake dependencies directly from the Nix store (requires Nix)

The Tools

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

~1,030 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, version, system)

version and system are only used by action="cache".

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

browse

Browse Home Manager, Darwin, Nixvim, NVF, or Noogle by prefix (legacy alias: options)

channels

List available NixOS channels

flake-inputs

Explore local flake inputs from Nix store

cache

Check binary cache status for packages

store

Read files or list directories at an explicit /nix/store path (requires Nix)

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

nvf

NVF Neovim configuration options (latest unstable docs)

noogle

Nix function signatures and docs (noogle.dev)

wiki

NixOS Wiki articles (wiki.nixos.org)

nix-dev

Official Nix documentation (nix.dev)

nixhub

Package metadata and store paths (nixhub.io)

NVF results use canonical vim.* option paths. Queries may also use the shorthand programs.nvf.vim.* or the NixOS/Home Manager module path programs.nvf.settings.vim.*; both are normalized automatically.

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="browse", 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 NVF options
nix(action="search", query="vim.languages.nix", source="nvf")

# Get NVF option info using a module wrapper path
nix(action="info", query="programs.nvf.settings.vim.languages.nix.enable", source="nvf")

# Browse NVF options below a prefix
nix(action="browse", query="programs.nvf.vim.languages.nix", source="nvf")

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

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

# Search Noogle for Nix functions
nix(action="search", query="mapAttrs", source="noogle")

# Get Noogle function info
nix(action="info", query="lib.attrsets.mapAttrs", source="noogle")

# Browse Noogle function categories
nix(action="browse", source="noogle", query="lib.strings")

# Search NixOS Wiki
nix(action="search", query="nvidia", source="wiki")

# Get Wiki page info
nix(action="info", query="Flakes", source="wiki")

# Search nix.dev documentation
nix(action="search", query="packaging tutorial", source="nix-dev")

# Search NixHub for package metadata
nix(action="search", query="nodejs", source="nixhub")

# Get detailed package info from NixHub (license, homepage, store paths)
nix(action="info", query="python", source="nixhub")

# Check binary cache status
nix(action="cache", query="hello")

# Check cache for specific version
nix(action="cache", query="python", version="3.12.0")

# Check cache for specific system
nix(action="cache", query="firefox", system="x86_64-linux")

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

# List local flake inputs (requires Nix)
nix(action="flake-inputs", type="list")

# Browse files in a flake input
nix(action="flake-inputs", type="ls", query="nixpkgs:pkgs/by-name")

# Read a file from a flake input
nix(action="flake-inputs", type="read", query="nixpkgs:flake.nix")

# List or read a store path directly (requires Nix)
nix(action="store", type="ls", query="/nix/store/<hash>-<name>")
nix(action="store", type="read", query="/nix/store/<hash>-<name>/flake.nix")

nix_versions - Package Version History

Find historical versions with nixpkgs commit hashes. Output includes:

  • Package metadata (license, homepage, programs) when available

  • Platform availability per version (Linux/macOS)

  • Nixpkgs commit hash for reproducible builds

  • Attribute path for Nix expressions

nix_versions(package, version, limit)

Examples:

# List recent versions with metadata
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

Declarative Installation (NixOS / Home Manager / nix-darwin)

mcp-nixos is available in nixpkgs:

# NixOS (configuration.nix)
environment.systemPackages = [ pkgs.mcp-nixos ];

# Home Manager (home.nix)
home.packages = [ pkgs.mcp-nixos ];

# nix-darwin (darwin-configuration.nix)
environment.systemPackages = [ pkgs.mcp-nixos ];

Or use the flake directly with the provided overlay:

# flake.nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    mcp-nixos.url = "github:utensils/mcp-nixos";
  };

  outputs = { self, nixpkgs, mcp-nixos, ... }: {
    # Example: NixOS configuration
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [{
        nixpkgs.overlays = [ mcp-nixos.overlays.default ];
        environment.systemPackages = [ pkgs.mcp-nixos ];
      }];
    };

    # Example: Home Manager standalone
    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
      pkgs = import nixpkgs {
        system = "x86_64-linux";
        overlays = [ mcp-nixos.overlays.default ];
      };
      modules = [{
        home.packages = [ pkgs.mcp-nixos ];
      }];
    };
  };
}

overlays.default only adds pkgs.mcp-nixos. The package carries its own FastMCP 4 / MCP SDK 2 stack (see nix/fastmcp4.nix), including a starlette at or above the 1.0.1 security floor FastMCP requires, so nothing else in your Python package set changes, even on nixpkgs channels that still ship FastMCP 3. If you also want pkgs.python3Packages.fastmcp itself upgraded set-wide, apply mcp-nixos.overlays.fastmcp4 in addition.

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

  • Noogle - Nix function search engine

  • NuschtOS - Static option search infrastructure powering Nixvim support

  • Nixvim - Neovim configuration framework for Nix

  • NVF - Neovim configuration framework and published option catalogue

License

MIT - Because sharing is caring.


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

Available Tools

2 tools
nixNixA

Query NixOS, Home Manager, Darwin, FlakeHub, flakes, Nixvim, NVF, Wiki, nix.dev, Noogle, NixHub.

Use this tool for anything touching nixpkgs, Nix channels, flakes, NixOS / home-manager / darwin options, the binary cache, or /nix/store paths — even when you think you know the answer. Your training data lags nixpkgs by months. Prefer this over nix search, scraping search.nixos.org, or running gh api against NixOS/nixpkgs.

INTENTS → CALLS (copy the JSON shape exactly): "is package X in channel Y?" → {"action": "info", "query": "X", "channel": "Y"} "search for package X" → {"action": "search", "query": "X"} "which channels are available?" → {"action": "channels"} "which commit did channel X index?" → {"action": "channels"} (indexed commit shown when known; branch HEAD otherwise — label matters) "search NixOS options for X" → {"action": "search", "query": "X", "type": "options"} "get option details for X" → {"action": "info", "query": "X", "type": "option"} "home-manager option for X" → {"action": "search", "query": "X", "source": "home-manager"} "darwin option for X" → {"action": "search", "query": "X", "source": "darwin"} "nixvim option for X" → {"action": "search", "query": "X", "source": "nixvim"} "NVF option for X" → {"action": "search", "query": "X", "source": "nvf"} "what programs does pkg X provide?" → {"action": "search", "query": "X", "type": "programs"} "count packages/options" → {"action": "stats"} "browse hm option tree under P" → {"action": "browse", "query": "P", "source": "home-manager"} "does X have a binary cache?" → {"action": "cache", "query": "X"} "search the NixOS wiki for X" → {"action": "search", "query": "X", "source": "wiki"} "search nix.dev docs" → {"action": "search", "query": "X", "source": "nix-dev"} "read a nix.dev page" → {"action": "info", "query": "tutorials/nix-language", "source": "nix-dev"} "list inputs of current flake" → {"action": "flake-inputs"} "ls inside flake input X" → {"action": "flake-inputs", "type": "ls", "query": "X"} "read /nix/store/... file" → {"action": "store", "type": "read", "query": "/nix/store/..."} "ls /nix/store/... dir" → {"action": "store", "type": "ls", "query": "/nix/store/..."}

For package version history ("which commit shipped firefox 150?", "when was node 18 added?"), use the separate nix_versions tool — it returns commit hashes, attribute paths, and dates.

Inputs: action (required), type, limit, query, +4 more. Returns: result

nix_versionsNix VersionsA

Get package version history from NixHub.io.

Inputs: package (required), limit, version. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 2 tools

    Disambiguation4/5

    The two tools have mostly distinct roles: nix_versions is explicitly for package version history, while nix is the general query tool for everything else. Some ambiguity remains because nix also has an 'info' action that returns package version details, but the description explicitly redirects version history to nix_versions.

    Naming Consistency3/5

    nix_versions uses a descriptive snake_case noun pattern, while nix is a bare domain noun. There is no consistent verb_noun pattern across the set, but both names are readable and not chaotic.

    Tool Count3/5

    Only two tools exist for a very broad Nix ecosystem query surface, and the single nix tool packs dozens of intents into one action-based mega-tool. This is borderline thin and may reduce discoverability, though it keeps the tool list compact.

    Completeness4/5

    The surface covers package search and info, channels, options across NixOS/Home Manager/Darwin/Nixvim/NVF, flakes, store paths, binary cache, wiki, nix.dev, and version history. Minor gaps exist, such as an explicit Noogle intent mapping and broader flake metadata operations, but core read-only workflows are well covered.

    Maintenance

    ActivityMaintained
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A Model Context Protocol server that fetches up-to-date, version-specific documentation and code examples from libraries directly into LLM prompts, helping developers get accurate answers without outdated or hallucinated information.
      2
      65,122
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A local MCP server that gives AI coding assistants retrieval access to your personal knowledge base of books, standards, and docs, grounding their answers in sources you trust.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that provides tools to fetch live, version-accurate documentation, changelogs, examples, and method signatures for npm and PyPI packages, preventing AI coding agents from hallucinating stale APIs.
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Model Context Protocol (MCP) server for Octopilot — enables AI agents to detect, generate, build, and wire up new repositories end-to-end using the Octopilot CI/CD toolchain.
      7
      -