MCP-NixOS

What is MCP-NixOS?

MCP-NixOS is a Model Context Protocol (MCP) server designed to provide AI assistants with precise and up-to-date information regarding the NixOS ecosystem. This includes details on NixOS packages, configuration options, Home Manager settings, and nix-darwin macOS configurations. Its primary goal is to prevent AI models from "hallucinating" or providing incorrect information when queried about Nix-related topics.

How to use MCP-NixOS?

MCP-NixOS can be used on any system (Windows, macOS, Linux) and does not require Nix/NixOS to be installed. It primarily queries web APIs. There are two main ways to use it:

• Using uvx (Recommended):

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

  Or, install globally: pip install mcp-nixos or uv pip install mcp-nixos.

• Using Nix (for Nix users):

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

  You can also run it without installing (nix run github:utensils/mcp-nixos) or install to your profile (nix profile install github:utensils/mcp-nixos).

Key Features of MCP-NixOS

• Real-time Data: Provides current information on NixOS packages, options, Home Manager settings, and nix-darwin configurations.
• Comprehensive Search Tools:
  • NixOS Tools: nixos_search, nixos_info, nixos_stats, nixos_channels, nixos_flakes_search, nixos_flakes_stats.
  • Version History Tools: nixhub_package_versions, nixhub_find_version (via NixHub.io).
  • Home Manager Tools: home_manager_search, home_manager_info, home_manager_stats, home_manager_list_options, home_manager_options_by_prefix.
  • Darwin Tools: darwin_search, darwin_info, darwin_stats, darwin_list_options, darwin_options_by_prefix.
• Cross-platform Compatibility: Works on Linux, macOS, and Windows.
• Simplified Architecture (v1.0.0): Rewritten for less code, 100% functionality, no cache corruption, stateless operation, and direct API access.
• User-Friendly Output: Provides plain text output, smart suggestions for typos, and enhanced error messages.
• No Configuration Needed: Designed for ease of use ("It just works™").

Use Cases of MCP-NixOS

• AI Assistant Enhancement: Empowers AI assistants (like those using Model Context Protocol) to provide accurate and up-to-date information about the NixOS ecosystem.
• Developer Productivity: Helps developers quickly find information on NixOS packages, options, and configurations without relying on potentially outdated or incorrect AI-generated content.
• System Administration: Assists SREs and DevOps professionals in managing NixOS environments by providing reliable data for troubleshooting and configuration.
• Learning and Exploration: Enables users to explore NixOS, Home Manager, and nix-darwin options systematically through various search and browsing tools.

FAQ about MCP-NixOS

• Do I need Nix/NixOS installed to use MCP-NixOS? No, you do not. It works on any system where Python runs, as it primarily queries web APIs.
• What kind of data does MCP-NixOS provide? It provides real-time information on NixOS packages, configuration options, Home Manager settings, nix-darwin macOS configurations, and package version history.
• What is the "Model Context Protocol"? It's a protocol that allows AI assistants to access external, real-time information, preventing them from generating incorrect or outdated responses.
• Has the project been significantly refactored? Yes, Version 1.0.0 is a complete rewrite that simplified the codebase by removing complex caching and abstractions while maintaining full functionality.
• Where does MCP-NixOS get its data from? It queries data from services like NixHub.io (for package version history) and search.nixos.org (for official NixOS package and option search).

MCP-NixOS - Because Your AI Assistant Shouldn't Hallucinate About Packages

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

Quick Start (Because You Want to Use It NOW)

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

Option 1: Using uvx (Recommended for most users)

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

Option 2: Using Nix (For Nix users)

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

What Is This Thing?

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)

The Tools You Actually Care About

🔍 NixOS Tools

• 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

📦 Version History Tools (NEW!)

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

🏠 Home Manager Tools

• 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 Tools

• 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

Installation Options

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

For Regular Humans (Windows/Mac/Linux)

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

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

For Nix Users (You Know Who You Are)

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

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

Features Worth Mentioning

🚀 Version 1.0.0: The Great Simplification

• 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

📊 What You Get

• 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™

🎯 Key Improvements

• 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

For Developers (The Brave Ones)

With Nix (The Blessed Path)

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

Without Nix (The Path of Pain)

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

Testing Philosophy

• 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

Environment Variables

Just one. We're minimalists now:

Variable	Description	Default
ELASTICSEARCH_URL	NixOS API endpoint	https://search.nixos.org/backend

Acknowledgments

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.

License

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.