Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/utensils--mcp-nixos/badge.svg)](/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

i

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)

  1. # MCP-NixOS - Because Your AI Shouldn't Hallucinate Package Names
  2. [![MCP Toplist](https://mcptoplist.com/badge/glama%2Futensils%2Fmcp-nixos.svg)](https://mcptoplist.com/server/glama%2Futensils%2Fmcp-nixos)
  3. [![CI](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml/badge.svg)](https://github.com/utensils/mcp-nixos/actions/workflows/ci.yml)
  4. [![codecov](https://codecov.io/gh/utensils/mcp-nixos/graph/badge.svg?token=kdcbgvq4Bh)](https://codecov.io/gh/utensils/mcp-nixos)
  5. [![PyPI](https://img.shields.io/pypi/v/mcp-nixos.svg)](https://pypi.org/project/mcp-nixos/)
  6. [![FlakeHub](https://img.shields.io/endpoint?url=https://flakehub.com/f/utensils/mcp-nixos/badge)](https://flakehub.com/flake/utensils/mcp-nixos)
  7. [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
  8. ![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)
  9. [![Built with Claude](https://img.shields.io/badge/Built%20with-Claude-D97757?logo=claude&logoColor=white)](https://claude.ai)
  10. ## Quick Start
  11. **🚨 No Nix/NixOS Required!** Works on any system - Windows, macOS, Linux. You're just querying APIs.
  12. ### Option 1: uvx (Recommended)
  13. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoidXZ4IG1jcC1uaXhvcyJ9)
  14. ```json
  15. {
  16. "mcpServers": {
  17. "nixos": {
  18. "command": "uvx",
  19. "args": ["mcp-nixos"]
  20. }
  21. }
  22. }
  23. ```
  24. ### Option 2: Nix
  25. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoibml4IHJ1biBnaXRodWI6dXRlbnNpbHMvbWNwLW5peG9zIC0tIn0%3D)
  26. ```json
  27. {
  28. "mcpServers": {
  29. "nixos": {
  30. "command": "nix",
  31. "args": ["run", "github:utensils/mcp-nixos", "--"]
  32. }
  33. }
  34. }
  35. ```
  36. ### Option 3: Docker
  37. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=nixos&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItLXJtIiwiLWkiLCJnaGNyLmlvL3V0ZW5zaWxzL21jcC1uaXhvcyJdfQ%3D%3D)
  38. ```json
  39. {
  40. "mcpServers": {
  41. "nixos": {
  42. "command": "docker",
  43. "args": ["run", "--rm", "-i", "ghcr.io/utensils/mcp-nixos"]
  44. }
  45. }
  46. }
  47. ```
  48. Your AI now has access to real NixOS data instead of making things up. You're welcome.
  49. ### Option 4: HTTP (Remote MCP)
  50. FastMCP supports running this server over HTTP at a URL (the MCP endpoint defaults to `/mcp`).
  51. ```bash
  52. # Run an HTTP MCP server at http://127.0.0.1:8000/mcp
  53. MCP_NIXOS_TRANSPORT=http MCP_NIXOS_HOST=127.0.0.1 MCP_NIXOS_PORT=8000 mcp-nixos
  54. ```
  55. STDIO (default):
  56. ```bash
  57. MCP_NIXOS_TRANSPORT=stdio mcp-nixos
  58. ```
  59. Custom path:
  60. ```bash
  61. MCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixos
  62. ```
  63. Stateless HTTP (disables per-client session state):
  64. ```bash
  65. MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixos
  66. ```
  67. ### Option 5: Pi Coding Agent
  68. [Pi](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) does not speak MCP natively. Two supported paths:
  69. **A. pi-mcp-adapter (recommended — speaks MCP, single source of truth):**
  70. ```bash
  71. pi install npm:pi-mcp-adapter
  72. ```
  73. Then add to `~/.pi/agent/mcp.json`:
  74. ```json
  75. {
  76. "mcpServers": {
  77. "nixos": {
  78. "command": "uvx",
  79. "args": ["mcp-nixos"],
  80. "lifecycle": "lazy"
  81. }
  82. }
  83. }
  84. ```
  85. **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.
  86. ## What Is This?
  87. An MCP server providing accurate, real-time information about:
  88. - **NixOS packages** - 130K+ packages that actually exist
  89. - **NixOS options** - 23K+ ways to configure your system
  90. - **Home Manager** - 5K+ options for dotfile enthusiasts
  91. - **nix-darwin** - 1K+ macOS settings Apple doesn't document
  92. - **Nixvim** - 5K+ options for Neovim configuration via [NuschtOS search](https://github.com/NuschtOS/search)
  93. - **NVF** - 2.4K+ Neovim options from its [published unstable documentation](https://nvf.notashelf.dev/options.html)
  94. - **FlakeHub** - 600+ flakes from [FlakeHub.com](https://flakehub.com) registry
  95. - **Noogle** - 2K+ Nix functions with type signatures via [noogle.dev](https://noogle.dev)
  96. - **NixOS Wiki** - Community documentation and guides from [wiki.nixos.org](https://wiki.nixos.org)
  97. - **nix.dev** - Official Nix tutorials and guides from [nix.dev](https://nix.dev)
  98. - **Package versions** - Historical versions with commit hashes via [NixHub.io](https://www.nixhub.io)
  99. - **Binary cache status** - Check if packages are cached on cache.nixos.org with download sizes
  100. - **Local flake inputs** - Explore your pinned flake dependencies directly from the Nix store (requires Nix)
  101. ## The Tools
  102. Just two. We consolidated 17 tools into 2 because your AI's context window isn't infinite.
  103. **~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.
  104. ### `nix` - Unified Query Tool
  105. One tool to rule them all:
  106. ```text
  107. nix(action, query, source, type, channel, limit, version, system)
  108. ```
  109. `version` and `system` are only used by `action="cache"`.
  110. | Action | What it does |
  111. |--------|-------------|
  112. | `search` | Search packages, options, programs, or flakes |
  113. | `info` | Get detailed info about a package or option |
  114. | `stats` | Get counts and categories |
  115. | `browse` | Browse Home Manager, Darwin, Nixvim, NVF, or Noogle by prefix (legacy alias: `options`) |
  116. | `channels` | List available NixOS channels |
  117. | `flake-inputs` | Explore local flake inputs from Nix store |
  118. | `cache` | Check binary cache status for packages |
  119. | `store` | Read files or list directories at an explicit `/nix/store` path (requires Nix) |
  120. | Source | What it queries |
  121. |--------|----------------|
  122. | `nixos` | Packages, options, programs |
  123. | `home-manager` | Home Manager options |
  124. | `darwin` | nix-darwin options |
  125. | `flakes` | Community flakes (search.nixos.org) |
  126. | `flakehub` | FlakeHub registry (flakehub.com) |
  127. | `nixvim` | Nixvim Neovim configuration options |
  128. | `nvf` | NVF Neovim configuration options (latest unstable docs) |
  129. | `noogle` | Nix function signatures and docs (noogle.dev) |
  130. | `wiki` | NixOS Wiki articles (wiki.nixos.org) |
  131. | `nix-dev` | Official Nix documentation (nix.dev) |
  132. | `nixhub` | Package metadata and store paths (nixhub.io) |
  133. NVF results use canonical `vim.*` option paths. Queries may also use the shorthand
  134. `programs.nvf.vim.*` or the NixOS/Home Manager module path
  135. `programs.nvf.settings.vim.*`; both are normalized automatically.
  136. **Examples:**
  137. ```python
  138. # Search NixOS packages
  139. nix(action="search", query="firefox", source="nixos", type="packages")
  140. # Get package info
  141. nix(action="info", query="firefox", source="nixos", type="package")
  142. # Search Home Manager options
  143. nix(action="search", query="git", source="home-manager")
  144. # Browse darwin options
  145. nix(action="browse", source="darwin", query="system.defaults")
  146. # Search Nixvim options
  147. nix(action="search", query="telescope", source="nixvim")
  148. # Get Nixvim option info
  149. nix(action="info", query="plugins.telescope.enable", source="nixvim")
  150. # Search NVF options
  151. nix(action="search", query="vim.languages.nix", source="nvf")
  152. # Get NVF option info using a module wrapper path
  153. nix(action="info", query="programs.nvf.settings.vim.languages.nix.enable", source="nvf")
  154. # Browse NVF options below a prefix
  155. nix(action="browse", query="programs.nvf.vim.languages.nix", source="nvf")
  156. # Search FlakeHub
  157. nix(action="search", query="nixpkgs", source="flakehub")
  158. # Get FlakeHub flake info
  159. nix(action="info", query="NixOS/nixpkgs", source="flakehub")
  160. # Search Noogle for Nix functions
  161. nix(action="search", query="mapAttrs", source="noogle")
  162. # Get Noogle function info
  163. nix(action="info", query="lib.attrsets.mapAttrs", source="noogle")
  164. # Browse Noogle function categories
  165. nix(action="browse", source="noogle", query="lib.strings")
  166. # Search NixOS Wiki
  167. nix(action="search", query="nvidia", source="wiki")
  168. # Get Wiki page info
  169. nix(action="info", query="Flakes", source="wiki")
  170. # Search nix.dev documentation
  171. nix(action="search", query="packaging tutorial", source="nix-dev")
  172. # Search NixHub for package metadata
  173. nix(action="search", query="nodejs", source="nixhub")
  174. # Get detailed package info from NixHub (license, homepage, store paths)
  175. nix(action="info", query="python", source="nixhub")
  176. # Check binary cache status
  177. nix(action="cache", query="hello")
  178. # Check cache for specific version
  179. nix(action="cache", query="python", version="3.12.0")
  180. # Check cache for specific system
  181. nix(action="cache", query="firefox", system="x86_64-linux")
  182. # Get stats
  183. nix(action="stats", source="nixos", channel="stable")
  184. # List local flake inputs (requires Nix)
  185. nix(action="flake-inputs", type="list")
  186. # Browse files in a flake input
  187. nix(action="flake-inputs", type="ls", query="nixpkgs:pkgs/by-name")
  188. # Read a file from a flake input
  189. nix(action="flake-inputs", type="read", query="nixpkgs:flake.nix")
  190. # List or read a store path directly (requires Nix)
  191. nix(action="store", type="ls", query="/nix/store/<hash>-<name>")
  192. nix(action="store", type="read", query="/nix/store/<hash>-<name>/flake.nix")
  193. ```
  194. ### `nix_versions` - Package Version History
  195. Find historical versions with nixpkgs commit hashes. Output includes:
  196. - Package metadata (license, homepage, programs) when available
  197. - Platform availability per version (Linux/macOS)
  198. - Nixpkgs commit hash for reproducible builds
  199. - Attribute path for Nix expressions
  200. ```python
  201. nix_versions(package, version, limit)
  202. ```
  203. **Examples:**
  204. ```python
  205. # List recent versions with metadata
  206. nix_versions(package="python", limit=5)
  207. # Find specific version
  208. nix_versions(package="nodejs", version="20.0.0")
  209. ```
  210. ## Installation
  211. **You DON'T need Nix installed.** This runs anywhere Python runs.
  212. ```bash
  213. # Run directly (no install)
  214. uvx mcp-nixos
  215. # Or install
  216. pip install mcp-nixos
  217. ```
  218. For Nix users:
  219. ```bash
  220. nix run github:utensils/mcp-nixos
  221. nix profile install github:utensils/mcp-nixos
  222. ```
  223. ### Declarative Installation (NixOS / Home Manager / nix-darwin)
  224. mcp-nixos is available in [nixpkgs](https://search.nixos.org/packages?channel=unstable&show=mcp-nixos&query=mcp-nixos):
  225. ```nix
  226. # NixOS (configuration.nix)
  227. environment.systemPackages = [ pkgs.mcp-nixos ];
  228. # Home Manager (home.nix)
  229. home.packages = [ pkgs.mcp-nixos ];
  230. # nix-darwin (darwin-configuration.nix)
  231. environment.systemPackages = [ pkgs.mcp-nixos ];
  232. ```
  233. Or use the flake directly with the provided overlay:
  234. ```nix
  235. # flake.nix
  236. {
  237. inputs = {
  238. nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
  239. mcp-nixos.url = "github:utensils/mcp-nixos";
  240. };
  241. outputs = { self, nixpkgs, mcp-nixos, ... }: {
  242. # Example: NixOS configuration
  243. nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
  244. system = "x86_64-linux";
  245. modules = [{
  246. nixpkgs.overlays = [ mcp-nixos.overlays.default ];
  247. environment.systemPackages = [ pkgs.mcp-nixos ];
  248. }];
  249. };
  250. # Example: Home Manager standalone
  251. homeConfigurations.myuser = home-manager.lib.homeManagerConfiguration {
  252. pkgs = import nixpkgs {
  253. system = "x86_64-linux";
  254. overlays = [ mcp-nixos.overlays.default ];
  255. };
  256. modules = [{
  257. home.packages = [ pkgs.mcp-nixos ];
  258. }];
  259. };
  260. };
  261. }
  262. ```
  263. `overlays.default` only adds `pkgs.mcp-nixos`. The package carries its own
  264. FastMCP 4 / MCP SDK 2 stack (see `nix/fastmcp4.nix`), including a starlette at
  265. or above the 1.0.1 security floor FastMCP requires, so nothing else in your
  266. Python package set changes, even on nixpkgs channels that still ship FastMCP 3.
  267. If you also want `pkgs.python3Packages.fastmcp` itself upgraded set-wide, apply
  268. `mcp-nixos.overlays.fastmcp4` in addition.
  269. ## Development
  270. ```bash
  271. nix develop # Enter dev shell
  272. nix build # Build package
  273. pytest tests/ # Run tests
  274. ruff check . # Lint
  275. ruff format . # Format
  276. mypy mcp_nixos/ # Type check
  277. ```
  278. ## Acknowledgments
  279. - **[NixHub.io](https://www.nixhub.io)** - Package version history
  280. - **[search.nixos.org](https://search.nixos.org)** - Official NixOS search
  281. - **[FlakeHub](https://flakehub.com)** - Flake registry by Determinate Systems
  282. - **[Jetify](https://www.jetify.com)** - Creators of Devbox and NixHub
  283. - **[Noogle](https://noogle.dev)** - Nix function search engine
  284. - **[NuschtOS](https://github.com/NuschtOS/search)** - Static option search infrastructure powering Nixvim support
  285. - **[Nixvim](https://github.com/nix-community/nixvim)** - Neovim configuration framework for Nix
  286. - **[NVF](https://github.com/NotAShelf/nvf)** - Neovim configuration framework and published option catalogue
  287. ## License
  288. MIT - Because sharing is caring.
  289. ---
  290. *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 in

Free to use. If it’s helped, pass it on.