NixOS MCP server for AI agents

MCP-NixOS is a Model Context Protocol server that provides your AI assistant with accurate, real-time information about NixOS packages, configuration options, Home Manager settings, and more. It helps prevent hallucinations about packages and system configurations by connecting to official data sources.

Installation Options

Quick Start

You don't need Nix or NixOS installed to use this tool - it works on any system including Windows, macOS, and Linux.

Option 1: Using uvx (Recommended)

# Run directly with uvx (no installation needed)
uvx mcp-nixos

Configure your MCP client with:

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

Option 2: Using Nix

# Run without installing
nix run github:utensils/mcp-nixos

Configure your MCP client with:

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

Option 3: Using Docker

# Run with Docker
docker run --rm -i ghcr.io/utensils/mcp-nixos

Configure your MCP client with:

{
  "mcpServers": {
    "nixos": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"]
    }
  }
}

Alternative Installation Methods

# Install globally with pip
pip install mcp-nixos

# Or with uv
uv pip install mcp-nixos

# For Nix users - install to profile
nix profile install github:utensils/mcp-nixos

Available Tools and Functions

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

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 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 categories
darwin_options_by_prefix(prefix) - Explore macOS options

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

For a permanent fix, add to your /etc/nix/nix.conf:

sandbox = relaxed

Environment Variables

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "nixos" '{"command":"uvx","args":["mcp-nixos"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect