mcp-nixos
MCP-NixOS - Model Context Protocol Server for NixOS resources
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/utensils/mcp-nixos with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/utensils/mcp-nixos'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/utensils--mcp-nixos)HTML
<a href="/listings/utensils--mcp-nixos"><img src="/api/listings/utensils--mcp-nixos/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**🚨 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](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):**
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 was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 391 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # MCP-NixOS - Because Your AI Shouldn't Hallucinate Package Names
- [](https://mcptoplist.com/server/glama%2Futensils%2Fmcp-nixos)
- [](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)
- - **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, version, system)
- ```
- `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) |
- | `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")
- # List or read a store path directly (requires Nix)
- nix(action="store", type="ls", query="/nix/store/<hash>-<name>")
- nix(action="store", type="read", query="/nix/store/<hash>-<name>/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 ];
- }];
- };
- };
- }
- ```
- `overlays.default` only adds `pkgs.mcp-nixos`. The package carries its own
- FastMCP 4 / MCP SDK 2 stack (see `nix/fastmcp4.nix`), including a starlette at
- or above the 1.0.1 security floor FastMCP requires, so nothing else in your
- Python package set changes, even on nixpkgs channels that still ship FastMCP 3.
- If you also want `pkgs.python3Packages.fastmcp` itself upgraded set-wide, apply
- `mcp-nixos.overlays.fastmcp4` in addition.
- ## 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.*
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.