🎉 REFACTORED: Version 1.0.0 represents a complete rewrite that drastically simplified everything. We removed all the complex caching, abstractions, and "enterprise" patterns. Because sometimes less is more, and more is just showing off.

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

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

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

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

MCP-NixOS is a Model Context Protocol server that gives your AI assistant accurate, real-time information about:

• NixOS packages (130K+ packages that actually exist)
• Configuration options (22K+ ways to break your system)
• Home Manager settings (4K+ options for the power users)
• nix-darwin configurations (1K+ macOS settings Apple doesn't want you to touch)
• Package version history via NixHub.io (Find that ancient Ruby 2.6 with commit hashes)

• nixos_search(query, type, channel) - Search packages, options, or programs
• nixos_info(name, type, channel) - Get detailed info about packages/options
• nixos_stats(channel) - Package and option counts
• nixos_channels() - List all available channels
• nixos_flakes_search(query) - Search community flakes
• nixos_flakes_stats() - Flake ecosystem statistics

• nixhub_package_versions(package, limit) - Get version history with commit hashes
• nixhub_find_version(package, version) - Smart search for specific versions

• home_manager_search(query) - Search user config options
• home_manager_info(name) - Get option details (with suggestions!)
• home_manager_stats() - See what's available
• home_manager_list_options() - Browse all 131 categories
• home_manager_options_by_prefix(prefix) - Explore options by prefix

• darwin_search(query) - Search macOS options
• darwin_info(name) - Get option details
• darwin_stats() - macOS configuration statistics
• darwin_list_options() - Browse all 21 categories
• darwin_options_by_prefix(prefix) - Explore macOS options

Remember: You DON'T need Nix/NixOS installed! This tool runs anywhere Python runs.

# Run directly with uvx (no installation needed)
uvx mcp-nixos

# Or install globally
pip install mcp-nixos
uv pip install mcp-nixos

# Run without installing
nix run github:utensils/mcp-nixos

# Install to profile
nix profile install github:utensils/mcp-nixos

• Drastically less code - Removed thousands of lines of complexity
• 100% functionality - Everything still works
• 0% cache corruption - Because we removed the cache entirely
• Stateless operation - No files to clean up
• Direct API access - No abstraction nonsense

• Real-time data - Always current, never stale
• Plain text output - Human and AI readable
• Smart suggestions - Helps when you typo option names
• Cross-platform - Works on Linux, macOS, and yes, even Windows
• No configuration - It just works™

• Dynamic channel resolution - stable always points to current stable
• Enhanced error messages - Actually helpful when things go wrong
• Deduped flake results - No more duplicate spam
• Version-aware searches - Find that old Ruby version you need
• Category browsing - Explore options systematically

nix develop
menu  # Shows all available commands

# Common tasks
run        # Start the server
run-tests  # Run all tests
lint       # Format and check code
typecheck  # Check types

pip install -e ".[dev]"
pytest tests/
black mcp_nixos/
flake8 mcp_nixos/

• 367 tests that actually test things
• Real API calls because mocks are for cowards
• Plain text validation ensuring no XML leaks through
• Cross-platform tests because Windows users deserve pain too

Just one. We're minimalists now:

This project queries data from several amazing services:

• NixHub.io - Provides package version history and commit tracking
• search.nixos.org - Official NixOS package and option search
• Jetify - Creators of Devbox and NixHub

Note: These services have not endorsed this tool. We're just grateful API consumers.

MIT - Because sharing is caring, even if the code hurts.

Created by James Brink and maintained by masochists who enjoy Nix.

Special thanks to the NixOS project for creating an OS that's simultaneously the best and worst thing ever.