https://github.com/utensils/mcp-nixos

MCP-NixOS - Model Context Protocol Server for NixOS resources
https://github.com/utensils/mcp-nixos

ai-assistant ai-integration ai-tools anthropic claude developer-tools devops-tools fastmcp llm-tools mcp model-context-protocol nix nix-options nix-packages nix-search nixos package-search python sre-tools

Last synced: 7 days ago
JSON representation

MCP-NixOS - Model Context Protocol Server for NixOS resources

Host: GitHub
URL: https://github.com/utensils/mcp-nixos
Owner: utensils
License: mit
Created: 2025-03-20T05:05:00.000Z (over 1 year ago)
Default Branch: main
Last Pushed: 2026-08-12T17:12:41.000Z (23 days ago)
Last Synced: 2026-08-19T16:48:05.182Z (16 days ago)
Topics: ai-assistant, ai-integration, ai-tools, anthropic, claude, developer-tools, devops-tools, fastmcp, llm-tools, mcp, model-context-protocol, nix, nix-options, nix-packages, nix-search, nixos, package-search, python, sre-tools
Language: Python
Homepage: https://mcp-nixos.io/
Size: 2.59 MB
Stars: 799
Watchers: 6
Forks: 44
Open Issues: 1
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
- Claude: CLAUDE.md
- Copilot: .github/copilot-instructions.md

Awesome Lists containing this project

awesome-mcp - utensils/mcp-nixos - NixOS - Model Context Protocol Server for NixOS resources ☆`384` (Developer Tools / CI/CD & DevOps)
awesome-mcp-servers - mcp-nixos - MCP server providing accurate information about NixOS packages, options, Home Manager, and nix-darwin macOS settings, helping prevent AI hallucinations. Example of a domain-specific MCP Server. ([Read more](/details/mcp-nixos.md)) `nixos` `linux` `configuration` `open-source` `ai-integration` (Data Access & Integration MCP Servers)
awesome - utensils/mcp-nixos - NixOS - Model Context Protocol Server for NixOS resources (MCP)
awesome-mcp-servers - utensils/mcp-nixos - سرور MCP که اطلاعات دقیقی در مورد بسته‌های NixOS، گزینه‌های سیستم، پیکربندی‌های Home Manager و تنظیمات nix-darwin macOS برای جلوگیری از توهمات هوش مصنوعی فراهم می‌کند. (پیاده‌سازی‌های سرور / 💻 <a name="developer-tools"></a>ابزارهای توسعه‌دهنده)
best-of-mcp-servers - GitHub - 1% open · ⏱️ 12.08.2026) (Developer Tools)
metorial-index - mcp-nixos - MCP-NixOS connects AI models to accurate NixOS documentation and package information, preventing misinformation and hallucinations about NixOS-related topics. It ensures reliable interactions with users seeking guidance on NixOS. (APIs and HTTP Requests)
toolsdk-mcp-registry - ✅ mcp-nixos - darwin configurations with multi-level caching and advanced search capabilities (18 tools) (python) (Developer Tools / How to Submit)
best-of-nix - GitHub - 35% open · ⏱️ 18.10.2025) (Development)
awesome-mcp - utensils/mcp-nixos - MCP-NixOS is a Model Context Protocol server that delivers accurate, real-time NixOS package and configuration data to AI assistants, preventing hallucinations and ensuring reliable information access. (MCP Servers / Cloud & DevOps)
awesome-mcp-servers - **MCP-NixOS** - A Model Context Protocol server that provides AI assistants with accurate, real-time information about NixOS packages, system options, Home Manager settings, and nix-darwin macOS configurations. `http` `ai` `git` `github` (📦 Other)
awesome-starred - utensils/mcp-nixos - MCP-NixOS - Model Context Protocol Server for NixOS resources (Python)
awesome-nix - MCP-NixOS - An MCP server that provides AI assistants with accurate information about NixOS packages, options, Home Manager, and nix-darwin configurations. (Development / Discovery)
awesome-openclaw-skills - utensils/mcp-nixos - NixOS - Model Context Protocol Server for NixOS resources | 519 | (MCP Servers & Protocol)
awesome-mcp-security - mcp-nixos - nixos) | (💻 Developer Tools (164 servers))

README

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

[![MCP Toplist](https://mcptoplist.com/badge/glama%2Futensils%2Fmcp-nixos.svg)](https://mcptoplist.com/server/glama%2Futensils%2Fmcp-nixos)

[![CI](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml/badge.svg)](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml)

[![codecov](https://codecov.io/gh/utensils/mcp-nixos/graph/badge.svg?token=kdcbgvq4Bh)](https://codecov.io/gh/utensils/mcp-nixos)

[![PyPI](https://img.shields.io/pypi/v/mcp-nixos.svg)](https://pypi.org/project/mcp-nixos/)

[![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/utensils/mcp-nixos/badge)](https://flakehub.com/flake/utensils/mcp-nixos)

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/utensils/mcp-nixos?utm_source=oss&utm_medium=github&utm_campaign=utensils%2Fmcp-nixos&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)

[![Built with Claude](https://img.shields.io/badge/Built%20with-Claude-D97757?logo=claude&logoColor=white)](https://claude.ai)

## Quick Start

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

### Option 1: uvx (Recommended)

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoidXZ4IG1jcC1uaXhvcyJ9)

```json

{

  "mcpServers": {

    "nixos": {

      "command": "uvx",

      "args": ["mcp-nixos"]

    }

  }

}

```

### Option 2: Nix

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoibml4IHJ1biBnaXRodWI6dXRlbnNpbHMvbWNwLW5peG9zIC0tIn0%3D)

```json

{

  "mcpServers": {

    "nixos": {

      "command": "nix",

      "args": ["run", "github:utensils/mcp-nixos", "--"]

    }

  }

}

```

### Option 3: Docker

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCJnaGNyLmlvL3V0ZW5zaWxzL21jcC1uaXhvcyJdfQ%3D%3D)

```json

{

  "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`).

```bash

# 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):

```bash

MCP_NIXOS_TRANSPORT=stdio mcp-nixos

```

Custom path:

```bash

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixos

```

Stateless HTTP (disables per-client session state):

```bash

MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos

```

### Option 5: Pi Coding Agent

[Pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) does not speak MCP natively. Two supported paths:

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

```bash

pi install npm:pi-mcp-adapter

```

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

```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](https://github.com/NuschtOS/search)

- **NVF** - 2.4K+ Neovim options from its [published unstable documentation](https://nvf.notashelf.dev/options.html)

- **FlakeHub** - 600+ flakes from [FlakeHub.com](https://flakehub.com) registry

- **Noogle** - 2K+ Nix functions with type signatures via [noogle.dev](https://noogle.dev)

- **NixOS Wiki** - Community documentation and guides from [wiki.nixos.org](https://wiki.nixos.org)

- **nix.dev** - Official Nix tutorials and guides from [nix.dev](https://nix.dev)

- **Package versions** - Historical versions with commit hashes via [NixHub.io](https://www.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.

### `nix` - Unified Query Tool

One tool to rule them all:

```text

nix(action, query, source, type, channel, limit)

```

| Action | What it does |

|--------|-------------|

| `search` | Search packages, options, programs, or flakes |

| `info` | Get detailed info about a package or option |

| `stats` | Get counts and categories |

| `browse` | Browse Home Manager, Darwin, Nixvim, NVF, or Noogle by prefix (legacy alias: `options`) |

| `channels` | List available NixOS channels |

| `flake-inputs` | Explore local flake inputs from Nix store |

| `cache` | Check binary cache status for packages |

| Source | What it queries |

|--------|----------------|

| `nixos` | Packages, options, programs |

| `home-manager` | Home Manager options |

| `darwin` | nix-darwin options |

| `flakes` | Community flakes (search.nixos.org) |

| `flakehub` | FlakeHub registry (flakehub.com) |

| `nixvim` | Nixvim Neovim configuration options |

| `nvf` | NVF Neovim configuration options (latest unstable docs) |

| `noogle` | Nix function signatures and docs (noogle.dev) |

| `wiki` | NixOS Wiki articles (wiki.nixos.org) |

| `nix-dev` | Official Nix documentation (nix.dev) |

| `nixhub` | Package metadata and store paths (nixhub.io) |

NVF results use canonical `vim.*` option paths. Queries may also use the shorthand

`programs.nvf.vim.*` or the NixOS/Home Manager module path

`programs.nvf.settings.vim.*`; both are normalized automatically.

**Examples:**

```python

# Search NixOS packages

nix(action="search", query="firefox", source="nixos", type="packages")

# Get package info

nix(action="info", query="firefox", source="nixos", type="package")

# Search Home Manager options

nix(action="search", query="git", source="home-manager")

# Browse darwin options

nix(action="browse", source="darwin", query="system.defaults")

# Search Nixvim options

nix(action="search", query="telescope", source="nixvim")

# Get Nixvim option info

nix(action="info", query="plugins.telescope.enable", source="nixvim")

# Search NVF options

nix(action="search", query="vim.languages.nix", source="nvf")

# Get NVF option info using a module wrapper path

nix(action="info", query="programs.nvf.settings.vim.languages.nix.enable", source="nvf")

# Browse NVF options below a prefix

nix(action="browse", query="programs.nvf.vim.languages.nix", source="nvf")

# Search FlakeHub

nix(action="search", query="nixpkgs", source="flakehub")

# Get FlakeHub flake info

nix(action="info", query="NixOS/nixpkgs", source="flakehub")

# Search Noogle for Nix functions

nix(action="search", query="mapAttrs", source="noogle")

# Get Noogle function info

nix(action="info", query="lib.attrsets.mapAttrs", source="noogle")

# Browse Noogle function categories

nix(action="browse", source="noogle", query="lib.strings")

# Search NixOS Wiki

nix(action="search", query="nvidia", source="wiki")

# Get Wiki page info

nix(action="info", query="Flakes", source="wiki")

# Search nix.dev documentation

nix(action="search", query="packaging tutorial", source="nix-dev")

# Search NixHub for package metadata

nix(action="search", query="nodejs", source="nixhub")

# Get detailed package info from NixHub (license, homepage, store paths)

nix(action="info", query="python", source="nixhub")

# Check binary cache status

nix(action="cache", query="hello")

# Check cache for specific version

nix(action="cache", query="python", version="3.12.0")

# Check cache for specific system

nix(action="cache", query="firefox", system="x86_64-linux")

# Get stats

nix(action="stats", source="nixos", channel="stable")

# List local flake inputs (requires Nix)

nix(action="flake-inputs", type="list")

# Browse files in a flake input

nix(action="flake-inputs", type="ls", query="nixpkgs:pkgs/by-name")

# Read a file from a flake input

nix(action="flake-inputs", type="read", query="nixpkgs:flake.nix")

```

### `nix_versions` - Package Version History

Find historical versions with nixpkgs commit hashes. Output includes:

- Package metadata (license, homepage, programs) when available

- Platform availability per version (Linux/macOS)

- Nixpkgs commit hash for reproducible builds

- Attribute path for Nix expressions

```python

nix_versions(package, version, limit)

```

**Examples:**

```python

# List recent versions with metadata

nix_versions(package="python", limit=5)

# Find specific version

nix_versions(package="nodejs", version="20.0.0")

```

## Installation

**You DON'T need Nix installed.** This runs anywhere Python runs.

```bash

# Run directly (no install)

uvx mcp-nixos

# Or install

pip install mcp-nixos

```

For Nix users:

```bash

nix run github:utensils/mcp-nixos

nix profile install github:utensils/mcp-nixos

```

### Declarative Installation (NixOS / Home Manager / nix-darwin)

mcp-nixos is available in [nixpkgs](https://search.nixos.org/packages?channel=unstable&show=mcp-nixos&query=mcp-nixos):

```nix

# NixOS (configuration.nix)

environment.systemPackages = [ pkgs.mcp-nixos ];

# Home Manager (home.nix)

home.packages = [ pkgs.mcp-nixos ];

# nix-darwin (darwin-configuration.nix)

environment.systemPackages = [ pkgs.mcp-nixos ];

```

Or use the flake directly with the provided overlay:

```nix

# flake.nix

{

  inputs = {

    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";

    mcp-nixos.url = "github:utensils/mcp-nixos";

  };

  outputs = { self, nixpkgs, mcp-nixos, ... }: {

    # Example: NixOS configuration

    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {

      system = "x86_64-linux";

      modules = [{

        nixpkgs.overlays = [ mcp-nixos.overlays.default ];

        environment.systemPackages = [ pkgs.mcp-nixos ];

      }];

    };

    # Example: Home Manager standalone

    homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {

      pkgs = import nixpkgs {

        system = "x86_64-linux";

        overlays = [ mcp-nixos.overlays.default ];

      };

      modules = [{

        home.packages = [ pkgs.mcp-nixos ];

      }];

    };

  };

}

```

## Development

```bash

nix develop          # Enter dev shell

nix build            # Build package

pytest tests/        # Run tests

ruff check .         # Lint

ruff format .        # Format

mypy mcp_nixos/      # Type check

```

## Acknowledgments

- **[NixHub.io](https://www.nixhub.io)** - Package version history

- **[search.nixos.org](https://search.nixos.org)** - Official NixOS search

- **[FlakeHub](https://flakehub.com)** - Flake registry by Determinate Systems

- **[Jetify](https://www.jetify.com)** - Creators of Devbox and NixHub

- **[Noogle](https://noogle.dev)** - Nix function search engine

- **[NuschtOS](https://github.com/NuschtOS/search)** - Static option search infrastructure powering Nixvim support

- **[Nixvim](https://github.com/nix-community/nixvim)** - Neovim configuration framework for Nix

- **[NVF](https://github.com/NotAShelf/nvf)** - Neovim configuration framework and published option catalogue

## License

MIT - Because sharing is caring.

---

*Created by James Brink. Maintained by mass̶o̶c̶h̶i̶s̶t̶s̶ enthusiasts who enjoy Nix.*

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/utensils/mcp-nixos

Awesome Lists containing this project

README