Github · GitHub Repository Radar
utensils mcp-nixos
MCP-NixOS - Model Context Protocol Server for NixOS resources
Stars
837
Forks
44
Watchers: 820
Language
License: MIT License
Repository Radar Score
45 / 100
Growth
- 7d
- +0
- 30d
- +0
- %
- 0.0%
Not enough metric snapshots yet to chart growth for this repository.
Last observed: 4 days ago
Score breakdown
- popularity 50
- growth 0
- activity 55
- freshness 100
- community 90
Need help integrating this stack?
Our team builds with modern open-source stacks. Tell us what you are shipping.
Get a quote →
🚨 No Nix/NixOS Required! Works on any system - Windows, macOS, Linux. You're just querying APIs.
{
"mcpServers": {
"nixos": {
"command": "uvx",
"args": ["mcp-nixos"]
}
}
}{
"mcpServers": {
"nixos": {
"command": "nix",
"args": ["run", "github:utensils/mcp-nixos", "--"]
}
}
}{
"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.
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-nixosSTDIO (default):
MCP_NIXOS_TRANSPORT=stdio mcp-nixosCustom path:
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_PATH=/api/mcp mcp-nixosStateless HTTP (disables per-client session state):
MCP_NIXOS_TRANSPORT=http MCP_NIXOS_STATELESS_HTTP=1 mcp-nixosPi does not speak MCP natively. Two supported paths:
A. pi-mcp-adapter (recommended — speaks MCP, single source of truth):
pi install npm:pi-mcp-adapterThen 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.
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)
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.
One tool to rule them all:
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:
# 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")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
nix_versions(package, version, limit)Examples:
# List recent versions with metadata
nix_versions(package="python", limit=5)
# Find specific version
nix_versions(package="nodejs", version="20.0.0")You DON'T need Nix installed. This runs anywhere Python runs.
# Run directly (no install)
uvx mcp-nixos
# Or install
pip install mcp-nixosFor Nix users:
nix run github:utensils/mcp-nixos
nix profile install github:utensils/mcp-nixosmcp-nixos is available in nixpkgs:
# 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:
# 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 ];
}];
};
};
}nix develop # Enter dev shell
nix build # Build package
pytest tests/ # Run tests
ruff check . # Lint
ruff format . # Format
mypy mcp_nixos/ # Type check- NixHub.io - Package version history
- search.nixos.org - Official NixOS search
- FlakeHub - Flake registry by Determinate Systems
- Jetify - Creators of Devbox and NixHub
- Noogle - Nix function search engine
- NuschtOS - Static option search infrastructure powering Nixvim support
- Nixvim - Neovim configuration framework for Nix
- NVF - Neovim configuration framework and published option catalogue
MIT - Because sharing is caring.
Created by James Brink. Maintained by mass̶o̶c̶h̶i̶s̶t̶s̶ enthusiasts who enjoy Nix.
Repository Radar analysis
Deterministic insights derived from public metadata and our observations — not personal testing or reviews.
Why this repository is interesting
- Listed in our discovery index with public GitHub metadata for analysis.
Who should use it
- Developers working primarily with Python
- Teams exploring AI tooling, agents, or ML infrastructure
- Platform and DevOps engineers
Potential use cases
- Reference or evaluate Python open-source approaches in this domain
- Prototype AI/agent workflows or study reference architectures
- Evaluate automation, CI/CD, or infrastructure patterns
Strengths
- README present in our index
- Declared license: MIT License
Limitations / considerations
- Insights are derived from public metadata and our observations — not a substitute for code review
What to watch
- Re-check last push, issues, and releases on GitHub before production adoption
Source: GitHub (public metadata) + Repository Radar analysis. We do not claim ownership of third-party repositories.