MCP-NixOS for Claude Code: Setup & Config

What you can do with MCP-NixOS in Claude Code

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

• Verify package names before proposing a Nix configuration.
• Check binary-cache availability or inspect local flake inputs.

Before you start: MCP-NixOS in Claude Code

• 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 Code configuration

1. Choose Claude Code configuration scope

   For MCP-NixOS, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add MCP-NixOS to Claude Code

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

3. Check MCP-NixOS in Claude Code

   MCP-NixOS: Inspect claude mcp list and /mcp status.

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

claude mcp add-json --scope project 'mcp-nixos' '{"type":"stdio","command":"uvx","args":["mcp-nixos"],"env":{}}'

MCP-NixOS tools available to Claude Code

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

nix

For MCP-NixOS's nix, review the permission request and arguments in Claude Code before approval.

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

nix_versions

For MCP-NixOS's nix_versions, review the permission request and arguments in Claude Code before approval.

MCP-NixOS: full stored tool descriptions

Troubleshooting MCP-NixOS in Claude Code

• If MCP-NixOS fails to start, check uvx mcp-nixos (from uv, for Python tools), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• MCP-NixOS uses stdio here: Claude Code 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 Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions