utensils/mcp-nixos

Quick Start
**🚨 No Nix/NixOS Required!** Works on any system - Windows, macOS, Linux. You're just querying APIs.
Option 1: uvx (Recommended)
Option 2: Nix
Option 3: Docker
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).
STDIO (default):
Custom path:
Stateless HTTP (disables per-client session state):
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):**
Then add to ~/.pi/agent/mcp.json:
**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.
nix - Unified Query Tool
One tool to rule them all:
version and system are only used by action="cache".
| 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 |
| store | Read files or list directories at an explicit /nix/store path (requires Nix) |
| 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) |