Mcp Nixos

What is Mcp Nixos about?

Mcp Nixos delivers a Model Context Protocol (MCP) server that queries official NixOS search APIs, NixHub version data, and related services. It exposes endpoints for packages, NixOS options, Home Manager settings, and nix‑darwin (macOS) configurations, allowing AI agents to obtain accurate, up‑to‑date information.

How to use Mcp Nixos?

Run the server – the project can be executed instantly with uvx mcp-nixos, installed via pip install mcp-nixos, launched with nix run github:utensils/mcp-nixos, or run in a Docker container (ghcr.io/utensils/mcp-nixos).

Add to your AI client – create a .mcp.json in the client’s working directory:

{
  "mcpServers": {
    "nixos": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-nixos", "mcp-nixos"]
    }
  }
}

The client will start the server automatically and route queries to it.

Query – use MCP‑compatible calls such as nixos_search, home_manager_info, or nixhub_package_versions from your assistant.

Key features of Mcp Nixos

Comprehensive data: 130k+ packages, 22k+ NixOS options, 4k+ Home Manager settings, 1k+ nix‑darwin options.
Version‑history lookup via NixHub, with commit hashes.
Async implementation on FastMCP 2.x for low‑latency responses.
Stateless, cache‑free operation – no files are written, guaranteeing fresh data.
Cross‑platform – runs on Windows, macOS, Linux without requiring Nix.
Smart suggestions – typo‑tolerant look‑ups and category browsing.
Simple installation – uvx, pip, Nix, or Docker.

Use cases of Mcp Nixos

AI‑powered dev assistance: let a coding assistant suggest exact NixOS package names and options while writing configuration files.
Documentation generation: automatically fetch up‑to‑date option descriptions for markdown docs.
CI/CD validation: validate that a given package or option exists before committing NixOS configurations.
Version‑specific builds: retrieve historic package versions to reproduce old environments.
Cross‑environment tooling: expose NixOS data to non‑Nix tools via MCP.

FAQ from the Mcp Nixos

Q: Do I need NixOS installed to use the server? A: No. The server only calls public web APIs, so it works on any system with Python.

Q: How does the server stay up‑to‑date? A: It queries the official search.nixos.org backend and NixHub in real time; no local cache is kept.

Q: What if I want to run it behind a firewall? A: Set the ELASTICSEARCH_URL environment variable to point to a reachable NixOS API endpoint.

Q: Can I limit the number of version entries returned? A: Yes. Use nixhub_package_versions(package, limit) to restrict the result set.

Q: Is there a Docker image? A: Yes – ghcr.io/utensils/mcp-nixos. Run it with docker run --rm -i ghcr.io/utensils/mcp-nixos.

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.

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

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

Option 2: Using Nix (For Nix users)

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

Option 3: Using Docker (Container lovers unite)

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

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)

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)

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)

# 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

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

Just one. We're minimalists now:

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

Troubleshooting

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:

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

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 and async/await patterns.

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

Mcp Nixos Overview