home / mcp / mcp nixos mcp server

MCP NixOS MCP Server

Provides real-time access to NixOS packages, options, and related resources via MCP with multiple transport options.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "utensils-mcp-nixos": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "MCP_NIXOS_HOST": "127.0.0.1",
        "MCP_NIXOS_PATH": "/api/mcp",
        "MCP_NIXOS_PORT": "8000",
        "MCP_NIXOS_TRANSPORT": "http",
        "MCP_NIXOS_STATELESS_HTTP": "1"
      }
    }
  }
}

You use this MCP server to query up-to-date information about NixOS, Home Manager, nix-darwin, Nixvim, and related resources through a single, flexible endpoint. You can run it locally, in containers, or remotely over HTTP, and you can choose the startup method that fits your workflow. This MCP server provides accurate data sources and convenient query actions to help you explore packages, options, and configurations across the Nix ecosystem.

How to use

To use this MCP server, connect with your MCP client using one of the supported transport methods. You can run the server locally and access it via STDIO, or expose it over HTTP for remote access. When you query, you can search for packages, options, and configuration details, retrieve detailed information, and check binary cache status across NixOS, Home Manager, nix-darwin, and related tools.

How to install

Prerequisites: ensure you have Python installed or use a compatible runtime. You can run the MCP server directly with Python, or install it as a package if you prefer.

Option A: Run directly (no install) using Python-enabled environment,

uvx mcp-nixos

Steps to install and run using common methods

Option 1: Install with uvx (recommended for a minimal setup) and run the MCP server directly.

uvx mcp-nixos

Option 2: Install with Nix (Nix/NixOS users) and run the MCP server

Use Nix to run or install the MCP server from the GitHub source.

nix run github:utensils/mcp-nixos
nix profile install github:utensils/mcp-nixos

Option 3: Run with Docker

Run the MCP server inside a Docker container for isolation and portability.

docker run --rm -i ghcr.io/utensils/mcp-nixos

Option 4: Serve over HTTP (remote MCP)

Expose the MCP server over HTTP so you can query from any client and integrate with your tooling. Use the provided environment variables to configure transport, host, and port.

# Run an HTTP MCP server at http://127.0.0.1:8000/mcp
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_HOST=127.0.0.1 MCP_NIXOS_PORT=8000 mcp-nixos

# STDIO (default):
MCP_NIXOS_TRANSPORT=stdio mcp-nixos

# Custom path:
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixos

# Stateless HTTP (no per-client sessions):
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

Additional usage notes

Your client can perform actions such as searching for packages, retrieving detailed information, checking channel availability, examining local flake inputs, and querying around NixOS Wiki and Nix dev resources. Use the actions you need to quickly discover package metadata, options, and related data.

Available tools

nix

A unified query tool to search, get info, and browse NixOS, Home Manager, and related sources.

nix_versions

Retrieve historical package versions and associated metadata from Nixpkgs.