1. Home
  2. MCP-NixOS
  3. MCP-NixOS for Claude Desktop: Setup & Config

Data as of

MCP-NixOS for Claude Desktop: Setup & Config

MCP-NixOS gives Claude Desktop live Nix ecosystem lookups instead of guessed package names and settings.

What you can do with MCP-NixOS in Claude Desktop

A compact two-tool interface for verified Nix ecosystem lookups and reproducible version references.

  • Verify package names before proposing a Nix configuration.
  • Find Home Manager, nix-darwin, or Nixvim options.

Before you start: MCP-NixOS in Claude Desktop

  • Python 3.11 or later
  • uv with uvx
  • Network access to queried data sources
  • Nix only for local flake-input operations

The README recommends uvx and states that ordinary API lookups do not need Nix. Docker and Nix launch alternatives are provided. HTTP mode is optional through MCP_NIXOS_TRANSPORT and related settings; stdio is the default. No required environment variables are stated for this launch.

MCP-NixOS Claude Desktop configuration

  1. Choose Claude Desktop configuration scope

    For MCP-NixOS, open macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json. Merge under mcpServers via Settings → Developer → Edit Config when available.

  2. Add MCP-NixOS to Claude Desktop

    Use the mcp-nixos entry below in mcpServers. Keep MCP-NixOS's documented stdio connection fields and your other Claude Desktop entries.

  3. Check MCP-NixOS in Claude Desktop

    MCP-NixOS: Fully quit and reopen Claude Desktop; check developer diagnostics.

Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

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

MCP-NixOS tools available to Claude Desktop

MCP-NixOS's stored tool list documents 2 tools; compare it with Claude Desktop's connected tool list, because the stored list is not a live check.

nix

When Claude Desktop requests nix from MCP-NixOS, review the action before approving it.

Query Nix packages, options, docs, functions, flakes, channels, cache status, and local flake inputs.

nix_versions

When Claude Desktop requests nix_versions from MCP-NixOS, review the action before approving it.

MCP-NixOS: full stored tool descriptions

Troubleshooting MCP-NixOS in Claude Desktop

  • Fully quit and reopen Claude Desktop for MCP-NixOS. If uvx mcp-nixos (from uv, for Python tools) is missing, check the desktop process's PATH, which may differ from your terminal.
  • MCP-NixOS uses stdio here: Claude Desktop must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
  • Known limitation: Local flake-input exploration still requires Nix.
  • Known limitation: API-backed lookups depend on reachable external data sources.
  • General Claude Desktop troubleshooting lives in the /clients/claude-desktop guide.

MCP-NixOS — details. Claude Desktop guide

Frequently asked questions

Claude Desktop loads MCP-NixOS from claude_desktop_config.json: ~/Library/Application Support/Claude/ on macOS, or %APPDATA%\Claude\ on Windows. Open it via Settings → Developer → Edit Config when available.

Claude Desktop's mcp-nixos example uses stdio.

MCP-NixOS's Claude Desktop configuration invokes uvx mcp-nixos (from uv, for Python tools).

MCP-NixOS's stored list contains 2 tools, including nix, nix_versions. Compare those names with Claude Desktop's connected tool list; the stored list is not a live check.

No. Ordinary queries call APIs and work on Windows, macOS, or Linux without Nix installed.

The README requires it for exploring local flake inputs from the Nix store.