The MCP-NixOS server provides accurate, real-time access to NixOS, Home Manager, and nix-darwin resources for AI assistants.
Search capabilities: Search for NixOS packages, options, or programs, including version-specific data across different channels (unstable, stable, and older)
Detailed information: Retrieve comprehensive details about specific NixOS packages and options
Home Manager support: Search configuration options, get detailed information, list top-level categories, and search by prefix
nix-darwin access: Interact with macOS configurations, including searching options and retrieving information about system and services
Statistics: Obtain usage data about available NixOS packages/options, Home Manager options, and nix-darwin configurations
Structured searches: Perform customizable searches with limits and channel preferences
This server helps AI assistants provide accurate NixOS-related information, reducing hallucinations and incorrect package suggestions.
Integrates with Codecov for tracking code coverage statistics from the project's test suite, with links to coverage reports.
Connects to the NixOS Elasticsearch API to query package information and system options with field-specific search boosts, multiple channel support, and error handling.
Offers specific integration for Firefox configuration in Home Manager, enabling access to Firefox profiles and settings information through dedicated search and info tools.
Provides access to Git configuration options in Home Manager, allowing AI assistants to retrieve information about Git username and other configuration settings.
Provides nix-darwin integration for macOS configuration options, allowing AI assistants to search and retrieve information about system defaults, services, and other macOS-specific settings that can be configured through nix-darwin.
Provides access to NGINX service configuration options in NixOS, allowing AI assistants to retrieve information about NGINX service settings.
Provides real-time access to NixOS packages and system options via the Elasticsearch API, allowing AI assistants to search and retrieve accurate information about available packages, their metadata, and system configuration options across multiple NixOS channels.
Enables access to PostgreSQL service configuration options in NixOS, allowing AI assistants to search and retrieve information about PostgreSQL service settings.
Provides integration with PyPI for package distribution, with version tracking and Python version compatibility information.
Offers integration with the yabai window manager configuration options in nix-darwin, providing access to service settings for macOS window management.
Provides access to Zsh shell configuration options in Home Manager, allowing AI assistants to search and retrieve information about Zsh settings.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-nixossearch for neovim packages in nixos"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: Notion MCP Server
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
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)Action | What it does |
| Search packages, options, programs, or flakes |
| Get detailed info about a package or option |
| Get counts and categories |
| Browse Home Manager/Darwin options by prefix |
| List available NixOS channels |
| Explore local flake inputs from Nix store |
| Check binary cache status for packages |
Source | What it queries |
| Packages, options, programs |
| Home Manager options |
| nix-darwin options |
| Community flakes (search.nixos.org) |
| FlakeHub registry (flakehub.com) |
| Nixvim Neovim configuration options |
| Nix function signatures and docs (noogle.dev) |
| NixOS Wiki articles (wiki.nixos.org) |
| Official Nix documentation (nix.dev) |
| Package metadata and store paths (nixhub.io) |
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")
# 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="options", 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
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-nixosFor Nix users:
nix run github:utensils/mcp-nixos
nix profile install github:utensils/mcp-nixosDeclarative 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 ];
}];
};
};
}Development
nix develop # Enter dev shell
nix build # Build package
pytest tests/ # Run tests
ruff check . # Lint
ruff format . # Format
mypy mcp_nixos/ # Type checkAcknowledgments
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
License
MIT - Because sharing is caring.
Created by James Brink. Maintained by mass̶o̶c̶h̶i̶s̶t̶s̶ enthusiasts who enjoy Nix.