mcp-nixos

Model Context Protocol Server for NixOS resources HTML-based implementation.

322 stars HTMLAI & Machine Learning Updated Nov 3, 2025

ai-assistantai-integrationai-toolsanthropicclaudedeveloper-toolsdevops-toolsfastmcpllm-toolsmcpmodel-context-protocolnixnix-optionsnix-packagesnix-searchnixospackage-searchpythonsre-tools

Documentation

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

Quick Start

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

Option 1: uvx (Recommended)

json

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

Option 2: Nix

json

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

Option 3: Docker

json

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

bash

# 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):

bash

MCP_NIXOS_TRANSPORT=stdio mcp-nixos

Custom path:

bash

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

Stateless HTTP (disables per-client session state):

bash

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):

bash

pi install npm:pi-mcp-adapter

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

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.

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:

text

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
`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

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:

python

# 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")

`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

python

nix_versions(package, version, limit)

Examples:

python

# 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.

bash

# Run directly (no install)
uvx mcp-nixos

# Or install
pip install mcp-nixos

For Nix users:

bash

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:

nix

# 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:

nix

# 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 ];
      }];
    };
  };
}

Development

bash

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.*

Frequently asked questions

What is mcp-nixos?

mcp-nixos is Model Context Protocol Server for NixOS resources HTML-based implementation.

How do I install mcp-nixos?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-nixos open source?

Yes — it is hosted on GitHub at https://github.com/utensils/mcp-nixos and has 322 stars.

Related MCP tools

unity-mcp

An MCP server that allows MCP clients like Claude Desktop or Cursor to perform actions in the Unity Editor C#-based implementation.

3,727 C#

aiai-integrationanthropic+15

apple-docs-mcp

MCP server for Apple Developer Documentation - Search iOS/macOS/SwiftUI/UIKit docs, WWDC videos, Swift/Objective-C APIs & code examples in Claude, Cursor & A...

552 TypeScript

ai-assistantapi-documentationapple+16

claude-debugs-for-you

Enable any LLM (e.g. Claude) to interactively debug any language for you via MCP and a VS Code Extension TypeScript-based implementation.

446 TypeScript

anthropicautodebugautomation+15

fastmcp

🚀 The fast, Pythonic way to build MCP servers and clients Trusted by 19900+ developers. Trusted by 19900+ developers. Trusted by 19900+ developers.

19,927 Python

agentsfastmcpllms+6

repomix

📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Lan...

19,761 TypeScript

aianthropicartificial-intelligence+17

firecrawl-mcp-server

🔥 Official Firecrawl MCP Server - Adds powerful web scraping and search to Cursor, Claude and any other LLM clients. JavaScript-based implementation.

4,847 JavaScript

batch-processingclaudecontent-extraction+11

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP