How to setup claude-cli and mcp-nixos on NixOS

I took a simple approach here by using a module style install. Create a claude.nix and drop this in it:

{ config, pkgs, lib, ... }:

with lib;

let
  # Import the unstable channel
  unstable = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-unstable.tar.gz") {
    config = config.nixpkgs.config;
  };
in {
  options.services.claude-cli = {
    enable = mkEnableOption "Claude CLI";

    package = mkOption {
      type = types.package;
      default = unstable.claude-code;
      description = "The Claude CLI package to use";
    };
  };

  config = mkIf config.services.claude-cli.enable {
    # Add claude-cli to system packages
    environment.systemPackages = [ 
      config.services.claude-cli.package
      pkgs.uv  # Add uv for when users want to install mcp-nixos manually
      pkgs.python3  # Make sure Python is available
    ];

    # Ensure the credentials directory exists and create config.json
    system.activationScripts.claude-cli-setup = ''
      mkdir -p ~/.claude-cli
      if [ ! -f ~/.claude-cli/credentials ]; then
        echo "# Add your Anthropic API key here" > ~/.claude-cli/credentials
        echo "# Format: ANTHROPIC_API_KEY=your_key_here" >> ~/.claude-cli/credentials
      fi
      
      # Create or update config.json with MCP server configuration
      cat > ~/.claude-cli/config.json << EOL
{
  "mcpServers": {
    "nixos": {
      "command": "uvx",
      "args": ["mcp-nixos"]
    }
  }
}
EOL

      # Create a helpful README file with setup instructions
      cat > ~/.claude-cli/README.md << EOL
# Claude CLI Setup for NixOS

## MCP Server Setup
To use the MCP server with Claude CLI, you need to install mcp-nixos:

\`\`\`bash
# Install mcp-nixos using one of these methods:
uv pip install mcp-nixos
# or
python -m pip install --user mcp-nixos
\`\`\`

## Configuration
The config.json file has been set up with the MCP server configuration.
EOL
    '';
  };
}

This will give us the claude command and the scaffolding for mcp-nixos to be easily installed. Next, make sure you add ./claude.nix as appropriate. I like a modules folder to keep things cleaner, so mine looks like ./modules/claude.nix . Don't forget to add services.claude-cli.enable = true; somewhere in your configuration.nix. Run sudo nixos-rebuild test for a sanity check. If it looks good, rebuild and test to make sure the command claude is available.

Next, we need to install the package. The module above explains that but I'm assuming you skipped reading it entirely. The GitHub provides three ways, you choose:

# Option 1: Install with pip like a normie
pip install mcp-nixos

# Option 2: Install with uv because you're too cool for pip
uv pip install mcp-nixos

# Option 3: Run directly with uvx (recommended for the truly enlightened)
uvx --install-deps mcp-nixos

You should be good from here. If not, use claude mcp add and choose the option where you tell it what the command line usage is to bring the server online and enter uvx mcp-nixos .

I'm 100% this could be cleaner, refined, and more nixified but it's good enough for now.

Links:
- https://mcp-nixos.io
- https://search.nixos.org/packages?channel=unstable&show=claude-code&from=0&size=50&sort=relevance&type=packages&query=claude+