Skip to content
<awesome-gh-repos>
vic

utensils/mcp-nixos

MCP-NixOS - Model Context Protocol Server for NixOS resources
Source code at GitHub https://mcp-nixos.io/
utensils/mcp-nixos.json
{
  "createdAt": "2025-03-20T05:05:00Z",
  "defaultBranch": "main",
  "description": "MCP-NixOS - Model Context Protocol Server for NixOS resources",
  "fullName": "utensils/mcp-nixos",
  "homepage": "https://mcp-nixos.io/",
  "language": "HTML",
  "name": "mcp-nixos",
  "pushedAt": "2025-10-18T21:00:18Z",
  "stargazersCount": 348,
  "topics": [
    "ai-assistant",
    "ai-integration",
    "ai-tools",
    "anthropic",
    "claude",
    "developer-tools",
    "devops-tools",
    "fastmcp",
    "llm-tools",
    "mcp",
    "model-context-protocol",
    "nix",
    "nix-options",
    "nix-packages",
    "nix-search",
    "nixos",
    "package-search",
    "python",
    "sre-tools"
  ],
  "updatedAt": "2025-11-26T20:47:34Z",
  "url": "https://github.com/utensils/mcp-nixos"
}

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

Section titled “MCP-NixOS - Because Your AI Assistant Shouldn’t Hallucinate About Packages”

CI codecov PyPI Python versions smithery badge Verified on MseeP

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

Section titled “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.

Section titled “Option 1: Using uvx (Recommended for most users)”

Install MCP Server

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

Option 2: Using Nix (For Nix users)

Section titled “Option 2: Using Nix (For Nix users)”

Install MCP Server

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

Option 3: Using Docker (Container lovers unite)

Section titled “Option 3: Using Docker (Container lovers unite)”

Install MCP Server

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

Section titled “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

Section titled “The Tools You Actually Care About”

🔍 NixOS Tools

Section titled “🔍 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!)

Section titled “📦 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

Section titled “🏠 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

Section titled “🍎 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

Section titled “Installation Options”

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

For Regular Humans (Windows/Mac/Linux)

Section titled “For Regular Humans (Windows/Mac/Linux)”
Terminal window
# 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)

Section titled “For Nix Users (You Know Who You Are)”
Terminal window
# Run without installing
nix run github:utensils/mcp-nixos


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

Features Worth Mentioning

Section titled “Features Worth Mentioning”

🚀 Version 1.0.1: The Async Revolution (After The Great Simplification)

Section titled “🚀 Version 1.0.1: The Async Revolution (After The Great Simplification)”
  • Drastically less code - v1.0.0 removed thousands of lines, v1.0.1 made them async
  • 100% functionality - Everything still works, now with more await
  • 0% cache corruption - Because we removed the cache entirely (still gone!)
  • Stateless operation - No files to clean up (async doesn’t change this)
  • Direct API access - No abstraction nonsense (but now it’s async nonsense)
  • Modern MCP - FastMCP 2.x because the old MCP was too synchronous

📊 What You Get

Section titled “📊 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

Section titled “🎯 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)

Section titled “For Developers (The Brave Ones)”

Local Development Setup

Section titled “Local Development Setup”

Want to test your changes in Claude Code or another MCP client? Create a .mcp.json file in your project directory:

{
  "mcpServers": {
    "nixos": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/hackerman/Projects/mcp-nixos",
        "mcp-nixos"
      ]
    }
  }
}

Replace /home/hackerman/Projects/mcp-nixos with your actual project path (yes, even you, Windows users with your C:\Users\CoolDev\... paths).

This .mcp.json file:

  • Automatically activates when you launch Claude Code from the project directory
  • Uses your local code instead of the installed package
  • Enables real-time testing - just restart Claude Code after changes
  • Already in .gitignore so you won’t accidentally commit your path

With Nix (The Blessed Path)

Section titled “With Nix (The Blessed Path)”
Terminal window
nix develop
menu  # Shows all available commands


# Common tasks
run        # Start the server (now with FastMCP!)
run-tests  # Run all tests (now async!)
lint       # Format and check code (ruff replaced black/flake8)
typecheck  # Check types (mypy still judges you)
build      # Build the package
publish    # Upload to PyPI (requires credentials)

Without Nix (The Path of Pain)

Section titled “Without Nix (The Path of Pain)”
Terminal window
# Install development dependencies
uv pip install -e ".[dev]"  # or pip install -e ".[dev]"


# Run the server locally
uv run mcp-nixos  # or python -m mcp_nixos.server


# Development commands
pytest tests/          # Now with asyncio goodness
ruff format mcp_nixos/ # black is so 2023
ruff check mcp_nixos/  # flake8 is for boomers
mypy mcp_nixos/        # Still pedantic as ever


# Build and publish
python -m build        # Build distributions
twine upload dist/*    # Upload to PyPI

Testing Philosophy

Section titled “Testing Philosophy”
  • 367 tests that actually test things (now async because why not)
  • Real API calls because mocks are for cowards (await real_courage())
  • Plain text validation ensuring no XML leaks through
  • Cross-platform tests because Windows users deserve pain too
  • 15 test files down from 29 because organization is a virtue

Environment Variables

Section titled “Environment Variables”

Just one. We’re minimalists now:

VariableDescriptionDefault
ELASTICSEARCH_URLNixOS API endpointhttps://search.nixos.org/backend

Troubleshooting

Section titled “Troubleshooting”

Nix Sandbox Error

Section titled “Nix Sandbox Error”

If you encounter this error when running via Nix:

error: derivation '/nix/store/...-python3.11-watchfiles-1.0.4.drv' specifies a sandbox profile,
but this is only allowed when 'sandbox' is 'relaxed'

Solution: Run with relaxed sandbox mode:

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

Why this happens: The watchfiles package (a transitive dependency via MCP) requires custom sandbox permissions for file system monitoring. This is only allowed when Nix’s sandbox is in ‘relaxed’ mode instead of the default ‘strict’ mode.

Permanent fix: Add to your /etc/nix/nix.conf:

sandbox = relaxed

Acknowledgments

Section titled “Acknowledgments”

This project queries data from several amazing services:

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

License

Section titled “License”

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

Created by James Brink and maintained by masochists who enjoy Nix and async/await patterns.

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