How to add MCP-NixOS to Claude Desktop

Real-time NixOS, Home Manager, nix-darwin, and Nixvim data so your AI stops hallucinating package and option names. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 705★ · stdio · no auth

Claude Desktop config for MCP-NixOS

uvx mcp-nixos

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

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the MCP-NixOS config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm MCP-NixOS's tools appear under the 🔌 tools menu.

Before you start

Python 3.11+ (when installed via pip/uvx)
uvx, pip, Nix, or Docker to run the server
Nix installed locally only for the flake-inputs action (querying local flake dependencies)

What MCP-NixOS can do in Claude Desktop

nix

Unified query tool: nix(action, query, source, type, channel, limit). Actions include search (packages/options/programs/flakes), info (detailed package/option info), stats (counts and categories), options (browse Home Manager/Darwin options by prefix), channels (list NixOS channels), flake-inputs (explore local flake inputs from the Nix store), and cache (check binary cache status). Sources include nixos, home-manager, darwin, flakes, flakehub, nixvim, noogle, wiki, nix-dev, and nixhub.

nix_versions

Package version history: nix_versions(package, version, limit). Finds historical versions with nixpkgs commit hashes; output includes package metadata (license, homepage, programs), platform availability per version (Linux/macOS), the nixpkgs commit hash for reproducible builds, and the attribute path for Nix expressions.

MCP-NixOS + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the MCP-NixOS config there under the "mcpServers" key and restart the client.

Do I need Nix or NixOS installed to use this?

No. It runs anywhere Python runs (Windows, macOS, Linux) and queries upstream APIs. Nix is only required for the flake-inputs action, which explores local flake dependencies from the Nix store.

How many tools does it expose?

Just two: nix (a unified query tool) and nix_versions (package version history). Seventeen underlying capabilities were consolidated into these two to keep the AI's context usage to roughly 1,030 tokens.

How do I run it over HTTP instead of stdio?

Set MCP_NIXOS_TRANSPORT=http (with optional MCP_NIXOS_HOST, MCP_NIXOS_PORT, and MCP_NIXOS_PATH). For example: MCP_NIXOS_TRANSPORT=http MCP_NIXOS_HOST=127.0.0.1 MCP_NIXOS_PORT=8000 mcp-nixos runs an HTTP MCP server at http://127.0.0.1:8000/mcp.

View repo Full MCP-NixOS page