nixmcp

# MCP-NixOS - Because Your AI Shouldn't Hallucinate Package Names [](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml) [](https://codecov.io/gh/utensils/mcp-nixos) [](https://pypi.org/project/mcp-nixos/) [](https://flakehub.com/flake/utensils/mcp-nixos) [](https://www.python.org/downloads/)  [](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) [](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoidXZ4IG1jcC1uaXhvcyJ9) ```json { "mcpServers": { "nixos": { "command": "uvx", "args": ["mcp-nixos"] } } } ``` ### Option 2: Nix [](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoibml4IHJ1biBnaXRodWI6dXRlbnNpbHMvbWNwLW5peG9zIC0tIn0%3D) ```json { "mcpServers": { "nixos": { "command": "nix", "args": ["run", "github:utensils/mcp-nixos", "--"] } } } ``` ### Option 3: Docker [](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) - **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 | | `options` | Browse Home Manager/Darwin options by prefix | | `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 | | `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) | **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="options", 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 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="options", 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 ## License MIT - Because sharing is caring. --- *Created by James Brink. Maintained by mass̶o̶c̶h̶i̶s̶t̶s̶ enthusiasts who enjoy Nix.*