GitHub - utensils/mcp-nixos: MCP-NixOS - Model Context Protocol Server for NixOS resources

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)

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

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

# 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

With Nix

nix develop
menu        # Show commands
run         # Start server
run-tests   # Run tests
lint        # Format + check
typecheck   # mypy

Without Nix

uv pip install -e ".[dev]"
uv run mcp-nixos
pytest tests/
ruff format mcp_nixos/
ruff check mcp_nixos/
mypy mcp_nixos/

Local MCP Testing

Create .mcp.json in your project:

{
  "mcpServers": {
    "nixos": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-nixos", "mcp-nixos"]
    }
  }
}

Troubleshooting

Nix Sandbox Error

nix run --option sandbox relaxed github:utensils/mcp-nixos --

Or add to /etc/nix/nix.conf:

Acknowledgments

NixHub.io - Package version history
search.nixos.org - Official NixOS search
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.