MCP-NixOS - Because Your AI Shouldn't Hallucinate Package Names

Quick Start

🚨 No Nix/NixOS Required! Works on any system - Windows, macOS, Linux. You're just querying APIs.

Option 1: uvx (Recommended)

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

Option 2: Nix

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

Option 3: Docker

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

Your AI now has access to real NixOS data instead of making things up. You're welcome.

Option 4: HTTP (Remote MCP)

FastMCP supports running this server over HTTP at a URL (the MCP endpoint defaults to /mcp).

# 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 (disables per-client session state):

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

Option 5: Pi Coding Agent

Pi does not speak MCP natively. Two supported paths:

A. pi-mcp-adapter (recommended — speaks MCP, single source of truth):

pi install npm:pi-mcp-adapter

Then add to ~/.pi/agent/mcp.json:

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

B. Project-local extension (clone + run): this repo ships .pi/extensions/mcp-nixos.ts, auto-loaded when you run pi in the cloned repo. Optional: cd .pi && npm install for editor type resolution. Pi runs it either way.

What Is This?

An MCP server providing accurate, real-time information about:

• NixOS packages - 130K+ packages that actually exist
• NixOS options - 23K+ ways to configure your system
• Home Manager - 5K+ options for dotfile enthusiasts
• nix-darwin - 1K+ macOS settings Apple doesn't document
• Nixvim - 5K+ options for Neovim configuration via NuschtOS search
• NVF - 2.4K+ Neovim options from its published unstable documentation
• FlakeHub - 600+ flakes from FlakeHub.com registry
• Noogle - 2K+ Nix functions with type signatures via noogle.dev
• NixOS Wiki - Community documentation and guides from wiki.nixos.org
• nix.dev - Official Nix tutorials and guides from nix.dev
• Package versions - Historical versions with commit hashes via NixHub.io
• Binary cache status - Check if packages are cached on cache.nixos.org with download sizes
• Local flake inputs - Explore your pinned flake dependencies directly from the Nix store (requires Nix)

The Tools

Just two. We consolidated 17 tools into 2 because your AI's context window isn't infinite.

~1,030 tokens total. That's it. While other MCP servers are hogging your context like it's Black Friday, we're sipping minimalist tea in the corner. Your AI gets NixOS superpowers without the bloat.