mcp-nixos

# MCP-NixOS - Because Your AI Assistant Shouldn't Hallucinate About Packages [](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml) [](https://codecov.io/gh/utensils/mcp-nixos) [](https://pypi.org/project/mcp-nixos/) [](https://pypi.org/project/mcp-nixos/) [](https://smithery.ai/server/@utensils/mcp-nixos) [](https://mseep.ai/app/99cc55fb-a5c5-4473-b315-45a6961b2e8c) > **🎉 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. > > **🚀 ASYNC UPDATE**: Version 1.0.1 migrated to FastMCP 2.x for modern async goodness. Because who doesn't love adding `await` to everything? ## 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) [](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoidXZ4IG1jcC1uaXhvcyJ9) ```json { "mcpServers": { "nixos": { "command": "uvx", "args": ["mcp-nixos"] } } } ``` ### Option 2: Using Nix (For Nix users) [](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoibml4IHJ1biBnaXRodWI6dXRlbnNpbHMvbWNwLW5peG9zIC0tIn0%3D) ```json { "mcpServers": { "nixos": { "command": "nix", "args": ["run", "github:utensils/mcp-nixos", "--"] } } } ``` ### Option 3: Using Docker (Container lovers unite) [](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCJnaGNyLmlvL3V0ZW5zaWxzL21jcC1uaXhvcyJdfQ%3D%3D) ```json { "mcpServers": { "nixos": { "command": "docker", "args": ["run", "--rm", "-i", "ghcr.io/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](https://www.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) ```bash # 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) ```bash # 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.1: The Async Revolution (After The Great Simplification) - **Drastically less code** - v1.0.0 removed thousands o