# mcp-nixos

> MCP-NixOS - Model Context Protocol Server for NixOS resources

- **URL**: https://www.freshcrate.ai/projects/mcp-nixos
- **Author**: utensils
- **Category**: MCP Servers
- **Latest version**: `v2.4.3` (2026-04-25)
- **License**: MIT
- **Source**: https://github.com/utensils/mcp-nixos
- **Homepage**: https://mcp-nixos.io/
- **Language**: Python
- **GitHub**: 597 stars, 33 forks
- **Registry**: github (`utensils/mcp-nixos`)
- **Tags**: `ai-assistant`, `ai-integration`, `ai-tools`, `anthropic`, `claude`, `developer-tools`, `devops-tools`, `fastmcp`, `python`

## Description

MCP-NixOS - Model Context Protocol Server for NixOS resources

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `v2.4.3` | 2026-04-25 | High | **MCP-NixOS v2.4.3** improves LLM discoverability of the server with a server-level `instructions` string, an INTENTS → CALLS recipe block in the `nix` tool, deterministic `action=info` matching that no longer silently substitutes packages with shared pnames, and per-channel nixpkgs HEAD revisions in `action=channels`.  **Closes #146.** Drop-in replacement for v2.4.2 — no configuration or API changes.  ### Highlights  - Server-level `instructions` surfaced via the MCP `InitializeResult` so hosts |
| `v2.4.2` | 2026-04-22 | High | ## Overview  MCP-NixOS v2.4.2 fixes a startup crash when the server is launched from a working directory containing a non-UTF-8 `.env` file (e.g. git-crypt ciphertext, sops-encrypted dotenv, or any binary blob).  Previously, `fastmcp`'s top-level `Settings()` construction ran python-dotenv on `.env` in the process CWD at import time, and a non-UTF-8 byte anywhere in that file took the whole server down with a `UnicodeDecodeError` — before the MCP stdio handshake ever ran. Clients (Claude Code, o |
| `v2.4.0` | 2026-04-21 | High | # MCP-NixOS: v2.4.0 Release Notes - FastMCP 3.x Upgrade  ## Overview  MCP-NixOS v2.4.0 upgrades the framework dependency to FastMCP 3.x (`fastmcp>=3.2.0`). No user-facing behavior changes — this is a dependency bump needed to keep the project buildable alongside downstream nixpkgs work that moves consumers (e.g. `ha-mcp`) onto FastMCP 3 (tracked in [NixOS/nixpkgs#511658](https://github.com/NixOS/nixpkgs/pull/511658)).  ## Changes in v2.4.0  ### 🚀 Framework  - **FastMCP 3.x upgrade** (#127, #130 |
| `v2.3.2` | 2026-04-21 | High | ## Overview  MCP-NixOS v2.3.2 improves the `nix` tool's descriptions and error messages so smaller local models (qwen3.6, qwen3-coder via Pi, etc.) can reliably map intent to the right `action`/`type` combo. Also ships a project-local Pi Coding Agent extension.  Addresses #123 and #125.  ## Highlights  - 🔧 **Rename `action=options` → `action=browse`** (#125) — the old name collided with "the options action" in models' minds; old name kept as silent alias for back-compat. - 🎯 **`browse` with `s |
| `v2.3.1` | 2026-04-03 | Medium | ## Overview  Fixes package search and info lookups for dotted/namespaced attribute paths (e.g., `kdePackages.qt6ct`, `python314Packages.matplotlib`).  ## Highlights - Search now queries `package_attr_name` and extracts pname from dotted names (#118) - Info lookup falls back to attribute path when pname lookup fails - Results display full attribute paths so users can identify package sets - Fixed circular symlinks between CLAUDE.md and AGENTS.md  ## Installation ```bash pip install mcp-nixos==2.3 |
| `v2.3.0` | 2026-03-06 | Low | ## Overview  MCP-NixOS v2.3.0 adds HTTP transport support for Remote MCP, binary cache status checking, NixHub as a rich metadata source, and restructures the codebase into a modular architecture.  ## Highlights  - **HTTP Transport** (#104): `MCP_NIXOS_TRANSPORT=http` with configurable host/port/path and stateless mode — by @ReStranger - **Binary Cache Status** (#92): `nix(action="cache")` checks if packages have pre-built binaries on cache.nixos.org - **NixHub Metadata** (#92): `nix(source="nix |
| `v2.2.0` | 2026-01-30 | Low | ## Overview  MCP-NixOS v2.2.0 adds three new documentation sources and a new flake-inputs action for exploring local Nix store dependencies.  ## Highlights  - 🔍 **NixOS Wiki** (`source="wiki"`) - Search and retrieve wiki articles - 📚 **nix.dev** (`source="nix-dev"`) - Search official Nix tutorials and guides - 🔧 **Noogle** (`source="noogle"`) - Search 2,000+ Nix built-in functions with type signatures - 📦 **Flake Inputs** (`action="flake-inputs"`) - Explore local Nix store dependencies (requ |
| `v2.1.1` | 2026-01-26 | Low | ## Overview  MCP-NixOS v2.1.1 fixes the Nix flake by using stable Python in nixpkgs and includes several build system improvements.  ## Changes in v2.1.1  ### 🔧 Improvements & Bug Fixes  - **Stable Python Compatibility**: Reverted from Python 3.14 to stable Python 3 in nixpkgs - **Version Retrieval Fix**: Dynamic version detection now reads from pyproject.toml when package isn't installed - **Flake Enhancements**: Better source filtering, unit tests run during build, versioned Docker tags - **C |
| `v2.1.0` | 2026-01-07 | Low | ## Overview  MCP-NixOS v2.1.0 converts to a pure Nix flake build system and adds FlakeHub integration. This release fixes build compatibility with nixpkgs-unstable (issue #67).  ## Highlights  - 🚀 **Pure Nix Flake**: Complete rewrite from hybrid venv/pip to pure Nix - 🌐 **FlakeHub Integration**: Now available on FlakeHub for easier installation - 🔧 **Build Fix**: Resolved fastmcp/mcp version constraint issue with nixpkgs-unstable - 🐍 **Python 3.14**: Now builds with Python 3.14 from nixpkgs |
| `v2.0.0` | 2026-01-06 | Low | ## Overview  MCP-NixOS v2.0.0 is a major release that consolidates 17 MCP tools into just 2 unified tools, reducing token overhead by 95%. This release also adds comprehensive Nixvim support with 16,600+ configuration options.  ## Highlights  ### 🎯 95% Token Reduction - **Before**: 17 individual tools consuming ~15,000 tokens - **After**: 2 unified tools consuming ~1,400 tokens   - `nix` (769 tokens) - Unified query tool   - `nix_versions` (643 tokens) - Package version history  ### 🚀 Nixvim S |

## Citation

- HTML: https://www.freshcrate.ai/projects/mcp-nixos
- Markdown: https://www.freshcrate.ai/projects/mcp-nixos.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/mcp-nixos/deps

_Generated by freshcrate.ai. Indexes github releases for AI-agent ecosystem packages._